内容
# forge-wiki
English · **[한국어](README.ko.md)** · **[日本語](README.ja.md)** · **[中文](README.zh.md)**
一个为LLM代理和与其合作的人类提供的受控Markdown维基。
大多数代理知识工具要么是完全自动化的记忆（mem0、Zep、Letta — 没有审批概念），要么是人工策划服务。forge-wiki处于两者之间：**代理编写，人类审核，索引自行维护。**
## 三项设计承诺
1. **内容经过策划，时效性由此而来。** `INDEX.md`中的`AUTO-INDEX`块会根据frontmatter和文件名日期重新生成 — 冲突解决后会重新生成，而不是手动解决。在并发多写入器模拟下验证（参见`tests/` — 50个写入器，包含损坏注入）。
2. **兼容OKF v0.1。** 文件为markdown + YAML frontmatter（`type`、`description`），保留`index.md`，链接作为边 — 可被任何OKF消费者读取，无锁定。
3. **作用域写入，审核合并。** 每个写入者拥有自己的文件；跨作者更改为提案（PR/移交），而非静默编辑。HITL是写入协议，而非功能标志。人类审核门旨在增加**品味** — 个人和组织判断 — 而非捕获缺陷：功能完整性是机器层的任务，通过模拟验证后才到达审阅者。
## 快速开始
无需安装：一个Python文件，除了`python3`外无其他依赖。克隆一次，放置在任何位置，通过路径调用。
```sh
git clone https://github.com/chrono-meta/forge-wiki.git ~/tools/forge-wiki
alias fw='python3 ~/tools/forge-wiki/bin/fw.py' # 可选 — 以下所有示例均使用 `fw`
cd your-knowledge-repo # 将持有维基的仓库 — 不是上面的克隆
fw init # 阶段0审计 + 非覆盖脚手架（创建 signals/）
mkdir -p memory # 添加其他任意分区；分区只是目录
# 将markdown文件放入分区目录中
fw sync --write # 重新生成时效索引 + llms.txt
fw doctor # 新鲜度 + 旧指针报告
```
**当`INDEX.md`中包含按分区和文件列出的`AUTO-INDEX`块且`fw check`退出状态为0时，您就成功了。** `doctor`是建议性的 — 非零退出状态是报告，而不是安装失败。
您的仓库现在看起来像这样：
```
your-knowledge-repo/
├── INDEX.md 顶部有策划的指针，下面有生成的 AUTO-INDEX 块
├── AGENTS.md 由 init 追加的维基协议块 — 面向代理的契约
├── llms.txt 每次 sync --write 时生成
├── memory/
└── signals/
```
在`INDEX.md`中发生合并冲突时：取任一侧，运行`fw heal --write`。完成。
## 您组织的实例
`fw init`为您提供一个可用的索引。它不会告诉您*要放入什么* — 这个决定使维基成为您的，任何工具都无法为您做出这个决定。
此构建的配对：**一个承载方法并设门控；维基承载您组织的上下文。** 两者不能替代。没有上下文着陆点的承载会重新导出相同的组织事实；没有承载的维基对进入的内容没有门控。
一个分区轴，经历了约2个月的每日运行（981个文件 — 四个最大分区持有73%）：
| 分区 | 持有 | 进入时机 |
|---|---|---|
| `memory/` | 持久事实，生命周期长于发现它的会话 | 需要再次使用且无法从代码中推导出的事实 |
| `tracks/<project>/` | 按项目划分的工作记录，累积 | 项目工作产生了值得重读的内容 |
| `signals/` | 可能重要的观察或测量 | 您注意到它 — 在知道它是否有价值之前记录下来 |
| `handoff/` | 在机器、会话或人之间传递的状态 | 下一个读取者不是当前写入者 |
| `audit/` | 按节奏进行的定期审查 | 节奏触发，而不是您感觉像时触发 |
| `digests/` | 循环外部扫描 | 自动化作业产生输出 |
从两个开始 — `memory/`和`signals/` — 并让分区在真正没有适合现有分区的第一个文件时出现。添加目录很便宜；**没有人写入的分区是删除它的信号，而不是填充它。**
**哪一个？** 两个问题解决了大多数文件。*能否从代码中重新导出？* — 如果是，则不属于`memory/`。*是否已做出判决？* — 如果否，则是`signals/`条目，而不是决策记录。
`examples/org-instance/`是一个最小的填充骨架。将其复制到您尚未`init`的仓库中 — 它带有自己的`INDEX.md`，而`fw init`拒绝覆盖：
```sh
cp -r ~/tools/forge-wiki/examples/org-instance/. your-knowledge-repo/
cd your-knowledge-repo
fw init # 保留复制的 INDEX.md，仍然追加 AGENTS.md 块
fw sync --write
```
## 子命令
| 命令 | 功能 | 失败方向 |
|---|---|---|
| `init` | 状态审计 + 脚手架（从不覆盖） | 存在文件时拒绝 |
| `sync [--write]` | 重新生成 AUTO-INDEX 块 | 默认情况下为干运行 |
| `heal [--write]` | 折叠冲突标记/重复块，然后同步 | 策略区域冲突保留人为 |
| `lint` | frontmatter 报告 | 仅报告，从不重写 |
| `doctor` | 新鲜度 + 旧指针报告 | 建议 |
| `check` | 索引漂移门控 | 漂移时退出状态1（CI阻止） |
## 状态
v0.1 — 从私有操作员维基的约2个月每日运行中提取：**981个markdown文件，57天中的50个提交，多机器**（2026-07-21测量 — `git ls-files '*.md' | wc -l`；存储本身保持私有）。`tests/`中的并发模拟是每个鲁棒性声明的回归锚点；此处断言的任何内容都未由模拟测量。
## 分发曲面
- `llms.txt`在每次`sync --write`时生成（导出，如索引）。
- `bin/fw_mcp.py` — 零依赖只读MCP服务器（`wiki_index` / `wiki_get` / `wiki_search`）。读取通过MCP；写入通过git + 门控 — 不对称是写入协议，而非缺少功能。
`claude mcp add forge-wiki -- python3 <abs>/bin/fw_mcp.py <wiki_root>`
参见`SPEC.md`以获取完整契约。
