Metadata-Version: 2.4
Name: invest-wiki-runtime
Version: 0.2.0
Summary: Deterministic runtime for invest-wiki agent skills
Author: xdsjs
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markitdown<0.2,>=0.1.1
Requires-Dist: requests<3,>=2.32
Dynamic: license-file

# 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`
  - 负责最终文章、维护检查与可复用查询输出

## 快速开始

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

```bash
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

```bash
npx skills add xdsjs/invest-llm-wiki
```

### 按需只安装单个 skill

```bash
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:

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

Codex:

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

OpenClaw:

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

### 安装 runtime

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

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

### 配置 root 并验证

```bash
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 相同的精确版本。建议至少先确认这些命令可用：

```bash
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 入口说明

## 开发与验证

常用本地命令：

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

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

```bash
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](AGENTS.md)
- 再看 [skills/invest-wiki-dossier/SKILL.md](skills/invest-wiki-dossier/SKILL.md)
- 然后看 [docs/contracts/page-model.md](docs/contracts/page-model.md)
- 最后按需进入 `src/invest_wiki_runtime/` 和 `tests/`
