invest-wiki-runtime 0.2.0

Deterministic runtime for invest-wiki agent skills

invest-llm-wiki

面向中文开发者的投资研究 wiki skill 包与配套 runtime 仓库，优先支持 Claude Code、Codex、OpenClaw。

这是什么

invest-llm-wiki 不是业务应用，也不是通用 SDK。它的定位是一个版本化的仓库入口，集中提供：

• 面向 agent 的投资研究 skill pack
• 发布到 PyPI 的 invest-wiki-runtime runtime package
• skill、runtime、repo surface 的契约测试
• preset、示例 wiki 与架构/契约文档

如果你是第一次进入这个仓库，可以把它理解成：

• 人和 agent 都能阅读的 skill catalog
• 一个由 python3 -m invest_wiki_runtime ... 驱动的已发布 PyPI package
• 一组围绕投资研究 wiki 工作流的约束、模板和验证脚本

核心能力

当前仓库里的核心能力主要分成 3 组：

• invest-wiki-dossier
  • ticker-first dossier workflow，skill 负责 inspect-first、模板选择与 checklist 管理；runtime 只提供 fetch-sources / materialize-source / write-artifact / validate-files 这些薄工具
• invest-wiki-ingest
  • 把新的原始材料编进 wiki 页面与相关 supporting notes
• invest-wiki-right-business / invest-wiki-right-people / invest-wiki-right-price
  • 维护业务、人物与治理、价格与赔率三条判断主线
• invest-wiki-article / invest-wiki-lint / invest-wiki-query
  • 负责最终文章、维护检查与可复用查询输出

快速开始

如果你只想先把东西跑起来，最短路径是：

npx skills add xdsjs/invest-llm-wiki
python3 -m pip install -U invest-wiki-runtime
python3 -m invest_wiki_runtime config set-root --root /absolute/path
python3 -m invest_wiki_runtime dossier fetch-sources --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier materialize-source --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier write-artifact --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier validate-files --ticker STZ --payload-file payload.json

runtime root 配置文件位于 ~/.config/invest-llm-wiki/config.toml。所有 skill 最终都会调用 python3 -m invest_wiki_runtime ...，所以先把 root 配好，后面的 dossier / ingest / lint / article 才会落到正确的 wiki 根目录。对 dossier 来说，先由 skill 读取 skills/invest-wiki-dossier/templates/checklist.org 与 skills/invest-wiki-dossier/templates/facts/us.org、hk.org、cn.org 之一，生成或更新 dossier/checklist.md，然后再按阶段调用 runtime CLI。

For Agent 安装 Skill

这一章给 Claude Code、Codex、OpenClaw 这类 agent 环境使用。边界很简单：

• skill 负责定义 workflow、guardrails 和当前 contract
• invest-wiki-runtime 负责真正执行 CLI 命令
• dossier 的模板选择与 checklist 管理由 skill 完成；runtime 只提供薄工具，不理解 checklist 语义

安装完整 skill pack

npx skills add xdsjs/invest-llm-wiki

按需只安装单个 skill

npx skills add xdsjs/invest-llm-wiki --skill invest-wiki-dossier
npx skills add xdsjs/invest-llm-wiki --skill invest-wiki-ingest
npx skills add xdsjs/invest-llm-wiki --skill invest-wiki-right-business
npx skills add xdsjs/invest-llm-wiki --skill invest-wiki-right-people
npx skills add xdsjs/invest-llm-wiki --skill invest-wiki-right-price
npx skills add xdsjs/invest-llm-wiki --skill invest-wiki-article
npx skills add xdsjs/invest-llm-wiki --skill invest-wiki-lint
npx skills add xdsjs/invest-llm-wiki --skill invest-wiki-query

按 agent 环境安装

Claude Code:

npx skills add xdsjs/invest-llm-wiki -g -a claude-code

Codex:

npx skills add xdsjs/invest-llm-wiki -g -a codex

OpenClaw:

npx skills add xdsjs/invest-llm-wiki -g -a openclaw

安装 runtime

invest-wiki-runtime 已作为 published PyPI package 发布，agent 侧统一安装最新版：

python3 -m pip install -U invest-wiki-runtime

配置 root 并验证

python3 -m invest_wiki_runtime config get-root
python3 -m invest_wiki_runtime config set-root --root /absolute/path
python3 -m invest_wiki_runtime dossier fetch-sources --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier materialize-source --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier write-artifact --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier validate-files --ticker STZ --payload-file payload.json

建议至少先确认这些命令可用：

runtime root 配置文件仍然是 ~/.config/invest-llm-wiki/config.toml。skill 会先检查 config get-root / config set-root，然后再执行对应业务命令。skill 文案默认安装最新已发布的 PyPI runtime 版本，不再要求 pin 到与 repo tag 相同的精确版本。建议至少先确认这些命令可用：

python3 -m invest_wiki_runtime dossier fetch-sources --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier materialize-source --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier write-artifact --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime dossier validate-files --ticker STZ --payload-file payload.json
python3 -m invest_wiki_runtime ingest --help
python3 -m invest_wiki_runtime lint --help

仓库结构

主要目录分工如下：

• skills/
  • canonical skill catalog；每个 skill 的 SKILL.md 描述当前已支持的 workflow 和 guardrails
• src/invest_wiki_runtime/
  • invest-wiki-runtime 的源码；CLI 入口与 dossier runtime 在这里
• scripts/
  • 仓库维护脚本，例如 surface sync 与 repo verification
• docs/contracts/
  • 页面模型与跨文件 contract
• docs/architecture/
  • adapter surface、repo structure 等架构说明
• presets/investment-research/
  • preset contract 与约束说明，不等于已经安装好的运行时 preset
• examples/minimal-company-wiki/
  • 最小示例 wiki 结构
• .claude/、.codex/、openclaw/
  • adapter-facing 入口说明

开发与验证

常用本地命令：

pytest -q
pytest tests/test_docs_contract.py -q
pytest tests/test_skill_catalog.py -q
python3 -m build

如果你在维护 repo surface，常用辅助脚本包括：

python3 scripts/sync/sync_surfaces.py
python3 scripts/verify/verify_repo.py

PyPI 发布由 .github/workflows/publish-runtime.yml 负责，按 tag v* 触发构建、smoke install 和 trusted publishing。

设计边界与文档索引

理解这个仓库时，建议把边界分成 3 层：

• AGENTS.md
  • 规定 spec 与 skill 的边界，避免把未来能力误写成当前 contract
• docs/contracts/
  • 定义当前页面与数据面的 contract
• docs/architecture/
  • 说明 adapter surfaces、repo layout 和结构约束

如果你想从最小语义单元开始读：

• 先看 AGENTS.md
• 再看 skills/invest-wiki-dossier/SKILL.md
• 然后看 docs/contracts/page-model.md
• 最后按需进入 src/invest_wiki_runtime/ 和 tests/