Beancount Plaintext Ledger

Beancount 纯文本复式记账框架，支持导入银行对账单和交易数据，自动生成资产负债表和损益表等财务报表。

Security Scan

The skill claims to be a Beancount plaintext ledger but its instructions mix accounting with a ZVT trading/backtest pipeline, reference running Python/pip checks and filesystem operations, and refer to external data providers without declaring any required credentials — these inconsistencies merit caution before installing or running it.

Purpose & Capability

Name/description present a Beancount plaintext double-entry ledger, but the SKILL.md and seed.yaml also embed a full data_collection->trading_execution pipeline (ZVT, MACD backtests, recorders, trading execution rules). The metadata claims Python 3.12+ and a uv package manager requirement (not expressed in the manifest requirements). The mix of ledger/accounting content with explicit trading/backtest workflow is unexpected and expands the skill's scope beyond a pure Beancount helper.

Instruction Scope

SKILL.md and seed.yaml instruct the agent to re-read seed.yaml, run precondition Python commands (import zvt, run recorders), check/create files under ZVT_HOME (~/.zvt), and potentially run pip install instructions if checks fail. The instructions reference external data providers (eastmoney, joinquant, akshare) and trading semantic locks that imply executing backtests/trades. Although no explicit shell commands are embedded as executable code files, the prose directs filesystem and network-affecting operations and gives broad discretion to install or import third-party packages — behavior that isn't confined to 'read-only' ledger parsing.

Install Mechanism

This is an instruction-only skill with no install spec or code files (lowest static install risk). However seed.yaml's execution_protocol references host install recipes and an 'install_trigger' flow which is not present in the manifest; that mismatch is ambiguous and could lead the agent to attempt pip installs at runtime. No downloads or archives are specified in the manifest itself.

Credentials

The skill declares no required environment variables or credentials, yet its instructions expect access to third-party data providers and to local configuration (ZVT_HOME path, writable ~/.zvt). Some data providers (joinquant, brokers) typically require API keys/cookies, but the skill does not declare or request them explicitly — this mismatch could lead the agent to prompt the user for credentials interactively or attempt to use any available system credentials. The seed/refs also instruct directory creation and pip installs, which require filesystem and network access but the manifest lists none of these as required.

Persistence & Privilege

The skill is not set to always:true and does not request persistent system-wide privileges. It does instruct agents to reload seed.yaml and to use workspace directories for scripts/skills, which is normal for complex instruction sets. There is no instruction to modify other skills' configurations, but the workflow does expect the agent to run precondition checks and possibly install or initialize environment state (e.g., pip install zvt, init ~/.zvt).

What to consider before installing

This skill mixes accounting (Beancount) and a ZVT-based trading/backtest pipeline. Before installing or running it: 1) Treat it as potentially able to run pip installs and write to your home directory (it checks/creates ~/.zvt) — run it in an isolated environment (VM or disposable container) first. 2) Expect prompts or implicit need for API keys for data providers (joinquant, brokers); do not enter production credentials until you verify the maintainer/source. 3) Verify the seed.yaml and references/LOCKS.md content yourself — the package reports only ~51% evidence verification and audit failures. 4) If you only want Beancount ledger parsing, prefer a dedicated Beancount skill/source; this one intentionally includes trading/backtest behavior that broadens its capabilities. 5) Ask the publisher/maintainer for the canonical source, a signed homepage/repo, and clarity on any install steps or credential needs before granting filesystem or network permissions.

Beancount 纯文本账本 (beancount-plaintext-ledger)

Beancount 纯文本复式记账框架，支持导入银行对账单和交易数据，自动生成资产负债表和损益表等财务报表。

Pipeline

data_collection -> data_storage -> factor_computation -> target_selection -> trading_execution -> visualization

Top Use Cases (2 total)

Beancount Test Utilities Framework (UC-101)

Provides reusable testing utilities for beancount test scripts including temporary directory management and test file creation for integration testing Triggers: testing utilities, tempdir, test files

Test Utils Validation Suite (UC-102)

Unit tests that validate the correctness of test utility functions including temporary directory cleanup and test file generation for beancount test s Triggers: unit test, validation, test utilities

Execute trigger: When user intent matches intent_router.uc_entries[].positive_terms AND user uses action verb (run/execute/跑/执行/backtest/fetch/collect)

What I'll Ask You

• Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin)
• Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)?
• Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor?
• Time range: start_timestamp and end_timestamp for backtest period
• Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)?

Semantic Locks (Fatal)

ID	Rule	On Violation
SL-01	Execute sell orders before buy orders in every trading cycle	halt
SL-02	Trading signals MUST use next-bar execution (no look-ahead)	halt
SL-03	Entity IDs MUST follow format entity_type_exchange_code	halt
SL-04	DataFrame index MUST be MultiIndex (entity_id, timestamp)	halt
SL-05	TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount	halt
SL-06	filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION	halt
SL-07	Transformer MUST run BEFORE Accumulator in factor pipeline	halt
SL-08	MACD parameters locked: fast=12, slow=26, signal=9	halt

Full lock definitions: references/LOCKS.md

Top Anti-Patterns (15 total)

• AP-ACCOUNTING-001: Using floating-point arithmetic for monetary amounts
• AP-ACCOUNTING-002: Skipping initialization calls before VM/script execution
• AP-ACCOUNTING-003: Mixing different asset types in monetary operations

All 15 anti-patterns: references/ANTI_PATTERNS.md

Evidence Quality Notice

[QUALITY NOTICE] This crystal was compiled from blueprint finance-bp-129. Evidence verify ratio = 51.5% and audit fail total = 7. Generated results may have uncaptured requirement gaps. Verify critical decisions against source files (LATEST.yaml / LATEST.jsonl).

Reference Files

File	Contents	When to Load
references/seed.yaml	V6+ 全量权威 (source-of-truth)	有行为/决策争议时必读
references/ANTI_PATTERNS.md	15 条跨项目反模式	开始实现前
references/WISDOM.md	跨项目精华借鉴	架构决策时
references/CONSTRAINTS.md	domain + fatal 约束	规则冲突时
references/USE_CASES.md	全量 KUC-* 业务场景	需要完整示例时
references/LOCKS.md	SL-* + preconditions + hints	生成回测/交易代码前
references/COMPONENTS.md	AST 组件地图（按 module 拆分）	查 API 时

---

Compiled by Doramagic crystal-compilation-v6.1 from finance-bp-129 blueprint at 2026-04-22T13:01:04.739311+00:00. See human_summary.md for non-technical overview.