trustwiki 0.1.0-alpha.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QianJinGuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,86 +1,206 @@
+<p align="center">
+  <img src="assets/hero.svg" alt="trustwiki — knowledge bases your agent can maintain, without lying to you" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/QianJinGuo/trustwiki/actions/workflows/ci.yml"><img src="https://github.com/QianJinGuo/trustwiki/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/trustwiki"><img src="https://img.shields.io/npm/v/trustwiki" alt="npm"></a>
+  <img src="https://img.shields.io/node/v/trustwiki" alt="node >= 18">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license">
+</p>
+
+English · [简体中文](README.zh.md)
+
 # trustwiki
 
-**Knowledge bases your agent can maintain — without lying to you.**
+**Your agent writes your notes. Who checks them?**
 
-Every claim cited. Contradictions surfaced. Rot detected.
+Every knowledge base maintained by an AI agent eventually rots the same way:
+claims nobody can trace, contradictions quietly rewritten away, links that
+die. trustwiki is the checker — it reads your markdown vault and tells you
+exactly where the rot is.
 
 ```bash
-npx trustwiki lint ./your-vault
+npx trustwiki lint ./your-notes
+```
+
+```text
+notes/model-comparison.md
+  L12   error citation.target-missing   citation target not found: sources/ghost.md
+  L14   warn  provenance.excess-inferred 3/5 prose paragraphs uncited (>0.3)
+  L16   warn  placeholder.present        placeholder text: TODO
+  L18   error link.broken                 broken wikilink [[notes/dead-ref]]
+
+Σ 3 errors, 5 warnings across 3 files
 ```
 
-trustwiki is a provenance linter and an operating method for knowledge bases
-maintained by AI agents. It does **not** build your wiki. It makes sure that
-when your agent does, every claim can be traced to a source, disagreements
-stay visible instead of being silently rewritten, and decay is measured —
-not discovered two months later.
+That is a real report on a vault seeded to fail. [See it run (10s GIF)](#2-see-it-run) · [What each finding means](#what-each-check-catches)
+
+## Why it exists
+
+AI agents already write knowledge bases — research wikis, team docs, personal
+notes. Nobody proofreads them, because the volume is inhuman. The failure mode
+is **fluent slop**: confident prose, zero provenance, contradictions resolved
+by whoever edits last.
+
+trustwiki is the discipline layer. It does **not** build your wiki — it makes
+sure that when your agent does, every claim traces to a source, disagreements
+stay visible, and decay is measured instead of discovered two months later.
+
+It is three things:
 
-- **12 mechanical checks** — citation grammar, citation targets, uncited-inference ratio, confidence floor, contradiction consistency, broken links, index drift, orphans, placeholders
-- **One config file** — `.trustwiki.json`; nothing configured, everything still runs
-- **Zero dependencies** — Node 18+, one command, JSON output for CI
-- **Proven in production** — [operating stats](proof/STATS.md) from an agent-maintained wiki running since 2026-05
+<p align="center">
+  <img src="assets/three-layers.svg" alt="Three layers: the checker (npx trustwiki lint), the spec (frozen citation grammar), the method (SKILL.md)" width="100%">
+</p>
 
-## Why
+- **A checker** — 12 mechanical checks: citations, contradictions, broken links, index drift, orphans
+- **A spec** — a frozen, versioned definition of "traceable": [schema/spec.md](schema/spec.md)
+- **A method** — the four-phase discipline your agent installs: [SKILL.md](SKILL.md)
 
-Agents are already writing knowledge bases. Without a trust layer they
-produce fluent slop: unattributed claims, silent contradiction resolution,
-links that rot. trustwiki is the discipline layer — the linter, the schema,
-and the method.
+## Getting started
 
-## Quick start
+### 1. Try it on the demo (30 seconds, nothing to install)
 
 ```bash
 git clone https://github.com/QianJinGuo/trustwiki && cd trustwiki
-npx trustwiki lint templates/demo-vault
+npx trustwiki lint templates/demo-vault     # a vault seeded to fail: 8 findings, exit 1
+npx trustwiki lint templates/starter-vault  # the same structure built to pass: exit 0
 ```
 
-You get a report like this (exit code 1 — errors present):
+### 2. See it run
 
-```
-notes/sloppy-page.md
-  L12   error citation.target-missing   citation target not found: sources/ghost.md
-  L14   warn  provenance.excess-inferred 3/5 prose paragraphs uncited (>0.3)
-  L16   warn  placeholder.present        placeholder text: TODO
-  ...
-Σ 3 errors, 5 warnings across 3 files
+![trustwiki linting the seeded demo vault — 8 findings](assets/demo.gif)
+
+### 3. Run it on your own vault
+
+Already keep notes in markdown (Obsidian, Logseq, plain files)? Just point at
+the directory. Zero config works:
+
+```bash
+npx trustwiki lint ~/Documents/my-notes
 ```
 
-The eight findings are seeded in `templates/demo-vault` — a vault built to
-fail. `templates/starter-vault` is the same structure built to pass, and is
-the starting point for your own vault.
+Most users then add one small `.trustwiki.json` at the vault root so the
+checker understands your layout:
 
-## The schema
+```json
+{
+  "roots": ["notes", "sources"],
+  "index": "index.md",
+  "sourceDir": "sources"
+}
+```
 
-The citation grammar (`^[path:42-58]`), provenance frontmatter, and
-contradiction marking are specified, versioned, and frozen at
-[schema/spec.md](schema/spec.md) (中文版: [spec.zh.md](schema/spec.zh.md)).
-Implementations other than this linter are welcome.
+- `roots` — which directories to scan
+- `index` — your index file, if you keep one (enables index-drift checks)
+- `sourceDir` — where raw captured sources live (enables citation-target
+  checks, and exempts those pages from "author's voice" rules — they quote,
+  they don't cite)
 
-## The method
+Full reference: [schema/spec.md](schema/spec.md).
 
-Four phases — **Ingest, Synthesize, Evolve, Gate** — as an installable agent
-skill: [SKILL.md](SKILL.md). Why each rule exists:
-[docs/method.md](docs/method.md) (中文版: [method.zh.md](docs/method.zh.md)).
 
-## Configuration
+### Already have an Obsidian / Logseq vault?
 
-Everything is optional. The two keys that matter:
+It works on your vault today, as-is — broken `[[wikilinks]]`, real TODOs, and
+dangling index entries are findable without any setup. If the provenance
+culture is not (yet) your vault's culture, switch off those rules and keep the
+checks that are language-agnostic:
 
 ```json
 {
-  "roots": ["notes", "sources"],
-  "index": "index.md",
-  "sourceDir": "sources"
+  "rules": {
+    "provenance.excess-inferred": "off",
+    "provenance.low-confidence": "off",
+    "citation.target-missing": "off",
+    "frontmatter.required": "warn",
+    "frontmatter.fields": "off"
+  }
 }
 ```
 
-Full reference in [schema/spec.md](schema/spec.md). Rule severities are
-`error | warn | off` per rule; exit codes are `0` clean, `1` errors,
-`2` usage/config.
+That is the honest floor: **broken-link and placeholder detection help any
+markdown vault**; the citation layer becomes valuable when you start capturing
+sources (see [SKILL.md](SKILL.md) Phase: Ingest).
+
+### 4. Make your agent maintain the vault under the same rules
+
+Install the method as an agent skill: copy
+[SKILL.md](SKILL.md) into your agent's skills directory (Claude Code, Codex,
+and most CLIs support project or global skills).
+
+<p align="center">
+  <img src="assets/four-phases.svg" alt="The four-phase loop: Ingest → Synthesize → Evolve → Gate; findings loop back" width="100%">
+</p>
+
+It teaches your agent the four phases with the violation consequences that
+motivated each rule. The short version of the whole method is one line:
+**never write a claim your vault cannot trace.**
+
+### 5. Gate your CI (optional)
+
+```bash
+npx trustwiki lint ./your-notes        # exit 0 = clean, 1 = errors present
+npx trustwiki lint ./your-notes --json # machine-readable for CI bots
+```
+
+## What each check catches
+
+| check | catches | example |
+|---|---|---|
+| `citation.malformed` | citations that don't parse — decoration, not provenance | `^[maybe a source?]` |
+| `citation.target-missing` | cited files that don't exist | `^[sources/ghost.md]` |
+| `provenance.excess-inferred` | pages that are mostly uncited prose | 3/5 paragraphs, no `^[…]` |
+| `provenance.low-confidence` | pages admitting they're shaky | `confidence: 0.3` |
+| `provenance.contradicted` | conflicts marked in body but not frontmatter (or vice versa) | callout without `contradicted_by` |
+| `link.broken` | `[[wikilinks]]` that resolve to nothing | `[[notes/dead-ref]]` |
+| `link.index-missing` | pages missing from the index; index entries that dangle | either direction |
+| `page.orphan` | pages with almost no outbound links — islands rot first | 0 links |
+| `frontmatter.required` / `.fields` | missing metadata; sources missing `sha256` (how silent edits get caught) | no `created` date |
+| `placeholder.present` | TODO/FIXME posing as finished content | `TODO: finish` |
+
+Severity of each is configurable (`error | warn | off`), warnings never fail
+the build, and the full rule reference lives in
+[schema/spec.md](schema/spec.md).
+
+## Proven in production
+
+<p align="center">
+  <img src="assets/precision-journey.svg" alt="Precision 49% to 93% after fixes; 8 foreign corpora, zero fabricated findings" width="100%">
+</p>
+
+This tool is the extracted discipline of an agent-maintained wiki that has
+run since 2026-05: **8,658 pages, 4,162 raw sources, 0 lint errors** — every
+number with source and verification date in [proof/STATS.md](proof/STATS.md).
+
+And the method itself was A/B tested on an identical task — one agent with
+SKILL.md, one without:
+
+<p align="center">
+  <img src="assets/ab-experiment.svg" alt="Without the method: 3 lint errors, no links, no sources. With it: 0 errors, 11 links, cited and tamper-evident" width="100%">
+</p>
+
+Re-run the experiment yourself in 30 seconds:
+[templates/eval-round3/](templates/eval-round3/) · full reports in [docs/eval/](docs/eval/).
+
+## FAQ
+
+**Is this for Obsidian/Logseq users or for agent builders?**
+Both. If you keep markdown notes, `npx trustwiki lint` finds rot today. If
+you build agents, [SKILL.md](SKILL.md) makes your agent write vaults that
+pass the same check.
+
+**Does it modify my files?**
+No. It reads and reports only. There is no `--fix` on purpose: fixes that
+matter require knowing which source supports the claim, and no tool can
+guess that for you.
 
-## Stats
+**Does it send my notes anywhere?**
+No. Local files in, stdout out. Zero dependencies, zero telemetry.
 
-Numbers from the production vault, each with source and verification date:
-[proof/STATS.md](proof/STATS.md).
+**My vault isn't agent-written — is this still useful?**
+Yes, if it has citations to check or links that can rot. The contradiction
+and broken-link checks help any markdown knowledge base.
 
 ## License
 

package/README.zh.md

@@ -1,81 +1,194 @@
+<p align="center">
+  <img src="assets/hero.svg" alt="trustwiki — 你的 agent 可以维护的知识库，前提是它不对你撒谎" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/QianJinGuo/trustwiki/actions/workflows/ci.yml"><img src="https://github.com/QianJinGuo/trustwiki/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/trustwiki"><img src="https://img.shields.io/npm/v/trustwiki" alt="npm"></a>
+  <img src="https://img.shields.io/node/v/trustwiki" alt="node >= 18">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license">
+</p>
+
+[English](README.md) · 简体中文
+
 # trustwiki
 
-**你的 agent 可以维护的知识库——前提是它不对你撒谎。**
+**你的 agent 在替你写笔记。谁在检查它们？**
 
-每个论断有引用。矛盾自动现形。腐烂有仪器测。
+所有由 AI agent 维护的知识库，最终都以同一种方式腐烂：没人能溯源的论断、
+被悄悄改写抹平的矛盾、死掉的链接。trustwiki 是检查器——它读你的 markdown
+知识库，精确告诉你烂在哪里。
 
 ```bash
-npx trustwiki lint ./your-vault
+npx trustwiki lint ./your-notes
+```
+
+```text
+notes/model-comparison.md
+  L12   error citation.target-missing   citation target not found: sources/ghost.md
+  L14   warn  provenance.excess-inferred 3/5 prose paragraphs uncited (>0.3)
+  L16   warn  placeholder.present        placeholder text: TODO
+  L18   error link.broken                 broken wikilink [[notes/dead-ref]]
+
+Σ 3 errors, 5 warnings across 3 files
 ```
 
-trustwiki 是一个溯源 linter，加一套面向 agent 维护知识库的操作方法。
-它**不**替你长出 wiki。它保证的是：当你的 agent 动笔时，每个论断能
-追溯到来源，分歧保持可见而不是被悄悄改写，腐烂被仪器测出来——
-而不是两个月后被人撞见。
+这是一座"造出来就是为了失败"的知识库上的真实报告。[看它运行（10 秒 GIF）](#2-看它运行) · [每条 finding 是什么意思](#每条检查抓什么)
+
+## 为什么有它
+
+AI agent 已经在替人写知识库——研究 wiki、团队文档、个人笔记。没人校对，
+因为工作量不是人能承受的。失败模式叫**流畅的 slop**：自信的散文、零溯源、
+矛盾被最后编辑的人悄悄裁决。
+
+trustwiki 是纪律层。它**不**替你长出 wiki——它保证的是：当你的 agent
+动笔时，每个论断能追溯到来源，分歧保持可见，腐烂被仪器测出来而不是
+两个月后被人撞见。
+
+它是三样东西：
 
-- **12 条机械检查**——引用文法、引用目标、未引用推断占比、置信度下限、矛盾一致性、断链、索引漂移、孤页、占位符
-- **一个配置文件**——`.trustwiki.json`；什么都不配置也照常能跑
-- **零依赖**——Node 18+，一条命令，JSON 输出可直接进 CI
-- **生产验证**——运行自 2026-05 的 agent 维护知识库的[活体统计](proof/STATS.md)
+<p align="center">
+  <img src="assets/three-layers.svg" alt="三层：检查器（npx trustwiki lint）、规范（冻结引用文法）、方法（SKILL.md）" width="100%">
+</p>
 
-## 为什么
+- **检查器**——12 条机械检查：引用、矛盾、断链、索引漂移、孤页
+- **规范**——"可溯源"的冻结版本化定义：[schema/spec.zh.md](schema/spec.zh.md)
+- **方法**——你的 agent 可安装的四阶段纪律：[SKILL.md](SKILL.md)
 
-agent 已经在替人写知识库了。没有信任层，它们产出的是流畅的 slop：
-无出处的论断、被静默抹平的矛盾、烂掉的链接。trustwiki 是纪律层——
-linter、schema、和方法。
+## 上手
 
-## 快速开始
+### 1. 在 demo 上试（30 秒，无需安装任何东西）
 
 ```bash
 git clone https://github.com/QianJinGuo/trustwiki && cd trustwiki
-npx trustwiki lint templates/demo-vault
+npx trustwiki lint templates/demo-vault     # 造出来为了失败的库：8 条 findings，退出码 1
+npx trustwiki lint templates/starter-vault  # 同样结构、造出来为了通过的库：退出码 0
 ```
 
-你会得到这样一份报告（退出码 1——存在 error）：
+### 2. 看它运行
 
-```
-notes/sloppy-page.md
-  L12   error citation.target-missing   citation target not found: sources/ghost.md
-  L14   warn  provenance.excess-inferred 3/5 prose paragraphs uncited (>0.3)
-  L16   warn  placeholder.present        placeholder text: TODO
-  ...
-Σ 3 errors, 5 warnings across 3 files
+![trustwiki 检查预埋缺陷的 demo vault——8 条 findings](assets/demo.gif)
+
+### 3. 用在你自己的知识库上
+
+已经在用 markdown 记笔记（Obsidian、Logseq、纯文件）？直接指向目录，
+零配置可用：
+
+```bash
+npx trustwiki lint ~/Documents/my-notes
 ```
 
-这 8 条 findings 是预埋在 `templates/demo-vault` 里的一座"造出来就是为了
-失败"的库。`templates/starter-vault` 是同样结构、造出来就是为了通过的库——
-也是你自己建库的起点。
+然后多数人会加一个小小的 `.trustwiki.json`，让检查器理解你的目录布局：
 
-## 规范
+```json
+{
+  "roots": ["notes", "sources"],
+  "index": "index.md",
+  "sourceDir": "sources"
+}
+```
 
-引用文法（`^[path:42-58]`）、provenance frontmatter、矛盾标记，全部
-有版本化的规范：[schema/spec.zh.md](schema/spec.zh.md)（English:
-[spec.md](schema/spec.md)）。欢迎 lint 之外的实现。
+- `roots`——扫描哪些目录
+- `index`——你的索引文件（可选，声明后启用索引漂移检查）
+- `sourceDir`——原始抓取来源所在目录（启用引用目标检查；这些页豁免
+  "作者声音"类规则——它们引用来源，不需要引用自己）
 
-## 方法
+完整参考：[schema/spec.zh.md](schema/spec.zh.md)。
 
-四个阶段——**Ingest、Synthesize、Evolve、Gate**——封装为可安装的
-agent skill：[SKILL.md](SKILL.md)。每条规则为什么存在：
-[docs/method.zh.md](docs/method.zh.md)（English: [method.md](docs/method.md)）。
 
-## 配置
+### 已经有一个 Obsidian / Logseq 库？
 
-一切可选。最重要的两个键：
+今天就能直接用——断掉的 `[[wikilink]]`、真实的 TODO、悬空的索引项，零配置
+即可找出。如果溯源文化还不是你的库的文化，把那部分规则先关掉，保留与语言
+无关的检查：
 
 ```json
 {
-  "roots": ["notes", "sources"],
-  "index": "index.md",
-  "sourceDir": "sources"
+  "rules": {
+    "provenance.excess-inferred": "off",
+    "provenance.low-confidence": "off",
+    "citation.target-missing": "off",
+    "frontmatter.required": "warn",
+    "frontmatter.fields": "off"
+  }
 }
 ```
 
-完整参考见 [schema/spec.zh.md](schema/spec.zh.md)。规则级别为
-`error | warn | off`；退出码 `0` 干净、`1` 有 error、`2` 用法/配置错误。
+这是诚实的下限：**断链与占位符检查对任何 markdown 库都有用**；引用层在
+你开始捕获来源后才会显现价值（见 [SKILL.md](SKILL.md) Phase: Ingest）。
+
+### 4. 让你的 agent 按同一套规则维护
+
+把方法装成 agent skill：复制 [SKILL.md](SKILL.md) 到你 agent 的 skills
+目录（Claude Code、Codex 和多数 CLI 都支持项目级或全局 skill）。
+
+<p align="center">
+  <img src="assets/four-phases.svg" alt="四阶段循环：Ingest → Synthesize → Evolve → Gate；findings 回流" width="100%">
+</p>
+
+它教你的 agent 四个阶段，以及每条规则背后的违规后果。整个方法的一句话
+版本：**永远不要写下你的知识库无法溯源的论断。**
+
+### 5. 进 CI 门禁（可选）
+
+```bash
+npx trustwiki lint ./your-notes        # 退出码 0 = 干净，1 = 有 error
+npx trustwiki lint ./your-notes --json # 机读输出，给 CI bot
+```
+
+## 每条检查抓什么
+
+| 检查 | 抓什么 | 例子 |
+|---|---|---|
+| `citation.malformed` | 解析不了的引用——是装饰不是溯源 | `^[maybe a source?]` |
+| `citation.target-missing` | 被引用的文件不存在 | `^[sources/ghost.md]` |
+| `provenance.excess-inferred` | 大部分段落无引用的页面 | 3/5 段落没有 `^[…]` |
+| `provenance.low-confidence` | 自己承认心虚的页面 | `confidence: 0.3` |
+| `provenance.contradicted` | 冲突只在正文标记、或只在 frontmatter 标记 | 有 callout 无 `contradicted_by` |
+| `link.broken` | 解析不到任何东西的 `[[wikilink]]` | `[[notes/dead-ref]]` |
+| `link.index-missing` | 页面不在索引里；或索引项悬空 | 双向都查 |
+| `page.orphan` | 几乎没有出链的页面——孤岛先腐烂 | 0 条出链 |
+| `frontmatter.required` / `.fields` | 缺元数据；来源页缺 `sha256`（静默篡改的发现手段） | 没有 `created` |
+| `placeholder.present` | 冒充完成品的 TODO/FIXME | `TODO: finish` |
+
+每条的严重度可配置（`error | warn | off`），warning 永远不导致失败，
+完整规则参考在 [schema/spec.zh.md](schema/spec.zh.md)。
+
+## 生产验证
+
+<p align="center">
+  <img src="assets/precision-journey.svg" alt="精确率 49%→93%；8 个外部语料零捏造" width="100%">
+</p>
+
+本工具是一套从真实运行中的 agent 维护知识库抽出的纪律——该库自 2026-05
+运行至今：**8,658 页、4,162 个原始来源、0 lint errors**——每个数字带来源
+和核实日期，见 [proof/STATS.md](proof/STATS.md)。
+
+方法本身也做了同任务 A/B 对照——一个 agent 带 SKILL.md，一个不带：
+
+<p align="center">
+  <img src="assets/ab-experiment.svg" alt="无方法：3 个 lint error、无链接、无来源。有方法：0 error、11 链接、可溯源防篡改" width="100%">
+</p>
+
+30 秒复跑这个实验：[templates/eval-round3/](templates/eval-round3/) · 完整报告在 [docs/eval/](docs/eval/)。
+
+## FAQ
+
+**是给 Obsidian/Logseq 用户还是给 agent 开发者？**
+都是。只要你用 markdown 记笔记，`npx trustwiki lint` 今天就能找出腐烂。
+如果你开发 agent，[SKILL.md](SKILL.md) 让你的 agent 写出能通过同一检查
+的知识库。
+
+**它会修改我的文件吗？**
+不会。只读、只报告。故意不做 `--fix`：真正要紧的修复需要知道哪个来源
+支撑哪个论断，没有工具能替你猜。
 
-## 活体统计
+**它会把我的笔记发到任何地方吗？**
+不会。本地文件进，stdout 出。零依赖，零遥测。
 
-来自生产库的数字，每个都带来源和核实日期：[proof/STATS.md](proof/STATS.md)。
+**我的库不是 agent 写的——还有用吗？**
+有用，只要它有可检查的引用或会烂的链接。矛盾和断链检查对任何 markdown
+知识库都有效。
 
 ## 许可
 

package/cli/bin.js

@@ -16,14 +16,20 @@ let json = false, configFlag, bad;
 for (let i = 2; i < args.length; i++) {
   if (args[i] === '--json') json = true;
   else if (args[i] === '--config') {
-    if (i + 1 >= args.length) { bad = '--config requires a file argument'; break; }
+    if (i + 1 >= args.length || args[i + 1].startsWith('--')) { bad = '--config requires a file argument'; break; }
     configFlag = args[++i];
   } else { bad = `unknown argument: ${args[i]}`; break; }
 }
 if (bad) { console.error(`trustwiki: ${bad}`); usage(); process.exit(2); }
 const { config, error } = await loadConfig(vault, configFlag);
 if (error) { console.error(`trustwiki: ${error.message}`); process.exit(2); }
-const findings = await lintVault(config.vaultPath, config);
+let findings;
+try {
+  findings = await lintVault(config.vaultPath, config);
+} catch (e) {
+  console.error(`trustwiki: failed to lint ${config.vaultPath}: ${e.message}`);
+  process.exit(2);
+}
 console.log(json ? formatJson(findings) : formatText(findings));
 // exitCode (not process.exit) so large stdout writes flush before teardown
 process.exitCode = findings.some(f => f.severity === 'error') ? 1 : 0;

package/cli/citations.js

@@ -1,6 +1,6 @@
 const CITATION_RE = /\^\[([^\]\n]*)\]/g;
-const RANGE_ANCHOR = /^(.+)#L(\d+)-L(\d+)$/;
-const RANGE_COLON = /^(.+?):(\d+)-(\d+)$/;
+const RANGE_ANCHOR = /^([^:\s]+)#L(\d+)-L(\d+)$/;
+const RANGE_COLON = /^([^:\s]+):(\d+)-(\d+)$/;
 
 export function parseCitation(raw) {
   const trimmed = raw.trim();
@@ -24,7 +24,7 @@ function parseSource(part) {
 
 function finish(path, start, end, part) {
   path = path.trim();
-  if (!path || /\s/.test(path)) return { ok: false, reason: `bad source syntax: "${part}"` };
+  if (!path || /[\s:]/.test(path)) return { ok: false, reason: `bad source syntax: "${part}" (path cannot contain spaces or colons)` };
   if (start !== null && (start < 1 || end < 1)) return { ok: false, reason: `line numbers must be positive in "${part}"` };
   if (start !== null && start > end) return { ok: false, reason: `reversed line range in "${part}" (start > end)` };
   return { ok: true, source: { path, start, end } };

package/cli/config.js

@@ -6,6 +6,7 @@ export const RULE_IDS = [
   'link.broken', 'link.index-missing', 'link.type-mismatch', 'page.orphan',
   'citation.malformed', 'citation.target-missing',
   'provenance.excess-inferred', 'provenance.low-confidence', 'provenance.contradicted',
+  'config.index-unreadable',
 ];
 
 const DEFAULT_SEVERITY = {
@@ -13,6 +14,7 @@ const DEFAULT_SEVERITY = {
   'link.broken': 'error', 'link.index-missing': 'warn', 'link.type-mismatch': 'warn', 'page.orphan': 'warn',
   'citation.malformed': 'error', 'citation.target-missing': 'error',
   'provenance.excess-inferred': 'warn', 'provenance.low-confidence': 'warn', 'provenance.contradicted': 'warn',
+  'config.index-unreadable': 'warn',
 };
 
 export const DEFAULT_CONFIG = {
@@ -36,6 +38,8 @@ export async function loadConfig(vaultPath, explicitPath) {
     user = JSON.parse(await readFile(configPath, 'utf8'));
   } catch (e) {
     if (e.code !== 'ENOENT') return { error: { message: `invalid ${configPath}: ${e.message}` } };
+    // an explicitly passed config file must exist — silent fallback would hide typos
+    if (explicitPath) return { error: { message: `config file not found: ${explicitPath}` } };
   }
   const rules = { ...DEFAULT_CONFIG.rules, ...(user.rules || {}) };
   const unknown = Object.keys(rules).filter(id => !RULE_IDS.includes(id));

package/cli/engine.js

@@ -4,20 +4,34 @@ import { walkVault } from './walk.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { extractWikilinks } from './links.js';
 import { findCitations } from './citations.js';
+import { normalizeTarget } from './resolve.js';
 import { RULES } from './rules/index.js';
 
-export function normalizeTarget(t) { return t.trim().replace(/\.md$/, ''); }
+export { normalizeTarget };
 
 // Mask fenced code blocks and inline code spans so their contents are never
 // treated as live citations/wikilinks. Character- and line-preserving: every
-// line number in the masked text matches the original file.
+// line number in the masked text matches the original file. Fence state tracks
+// the delimiter type — a ``` line inside a ~~~ fence is content, not a closer.
 export function maskCode(body) {
   const lines = body.split('\n');
-  let inFence = false;
+  const fenceRe = /^\s*(`{3,}|~{3,})/;
+  let fenceMark = null;
   const masked = lines.map(line => {
-    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; return ''; }
-    if (inFence) return '';
-    return line.replace(/`[^`\n]*`/g, m => '`' + ' '.repeat(Math.max(0, m.length - 2)) + '`');
+    const m = line.match(fenceRe);
+    if (m) {
+      const mark = m[1][0];
+      if (!fenceMark) { fenceMark = mark; return ''; }
+      if (mark === fenceMark) { fenceMark = null; }
+      return '';
+    }
+    if (fenceMark) return '';
+    // mask inline HTML tag content (<tt>, <code>, <kbd>…) — regex literals like
+    // ^[a-zA-Z]*$ live there in real-world docs (k8s CEL reference)
+    return line
+      .replace(/<([a-z][a-z0-9]*)\b[^>]*>([\s\S]*?)<\/\1>/gi,
+        (_, tag, inner) => `<${tag}>${' '.repeat(inner.length)}</${tag}>`)
+      .replace(/`[^`\n]*`/g, x => '`' + ' '.repeat(Math.max(0, x.length - 2)) + '`');
   });
   return masked.join('\n');
 }
@@ -48,13 +62,15 @@ export async function lintVault(vaultPath, config) {
   if (config.index) {
     try {
       const raw = await readFile(join(vaultPath, config.index), 'utf8');
+      const indexMasked = maskCode(raw);
       model.indexRaw = raw;
       model.indexEntries = new Set();
       model.indexLines = new Map();
-      const indexLines = raw.split('\n');
+      const indexLines = indexMasked.split('\n');
       for (let i = 0; i < indexLines.length; i++) {
         for (const m of indexLines[i].matchAll(/\[\[([^\]|\n]+)/g)) {
-          const norm = normalizeTarget(m[1]);
+          const norm = normalizeTarget(m[1].split('#')[0]);
+          if (!norm) continue;
           model.indexEntries.add(norm);
           if (!model.indexLines.has(norm)) model.indexLines.set(norm, i + 1);
         }
@@ -71,7 +87,7 @@ export async function lintVault(vaultPath, config) {
     const bodyStartLine = fm.bodyStartLine;
     const body = maskCode(fm.body);
     model.files.push({
-      relPath: rel, text, fm, body: fm.body, bodyStartLine,
+      relPath: rel, text, fm, body, bodyStartLine, // body is masked: rules never see code-fence content
       links: extractWikilinks(body, bodyStartLine),
       ...findCitations(body, bodyStartLine),
       paragraphs: proseParagraphs(body, bodyStartLine),
@@ -91,7 +107,8 @@ export async function lintVault(vaultPath, config) {
     }
   }
   if (indexUnreadable) {
-    findings.push({ severity: 'warn', rule: 'config.index-unreadable', file: config.index, line: 1,
+    findings.push({ severity: config.rules['config.index-unreadable'] || 'warn',
+      rule: 'config.index-unreadable', file: config.index, line: 1,
       message: 'configured index could not be read; index rules disabled',
       hint: 'check the path or remove the index key from .trustwiki.json' });
   }

package/cli/links.js

@@ -1,4 +1,4 @@
-const WIKILINK_RE = /\[\[([^\]|\n]+)(?:\|([^\]\n]*))?\]\]/g;
+const WIKILINK_RE = /\[\[([^\]|\n]+)(?:\|([^\]\n]*))?\]\](?!\s*\()/g;
 
 export function extractWikilinks(body, bodyStartLine) {
   const out = [];

package/cli/report.js

@@ -1,4 +1,6 @@
-const CONTROL = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+// strip ALL control chars including CR/LF and C1 — a hostile vault must not be
+// able to forge report lines or overwrite terminal rows via file names
+const CONTROL = /[\x00-\x1F\x7F-\x9F]/g;
 const clean = s => String(s).replace(CONTROL, '');
 
 export function formatText(findings) {

package/cli/resolve.js

@@ -1,4 +1,4 @@
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, realpathSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 
 export function normalizeTarget(t) { return t.trim().replace(/\.md$/, ''); }
@@ -13,13 +13,20 @@ export function resolveTarget(t, cfg) {
   return cands;
 }
 
-// Contained, regular-file existence check. Rejects `../` escapes, symlink
-// escapes, and directory hits — a citation/probe must never leave the vault.
+// Contained, regular-file existence check. Realpath-based: an in-vault symlink
+// pointing outside the vault resolves outside and is rejected. Rejects `../`
+// escapes and directory hits — a citation/probe must never leave the vault.
 export function resolveInVault(vaultPath, cand) {
-  const vaultRoot = resolve(vaultPath);
-  const abs = resolve(vaultRoot, cand);
-  if (abs !== vaultRoot && !abs.startsWith(vaultRoot + sep)) return null;
+  const abs = resolve(vaultPath, cand);
   if (!existsSync(abs)) return null;
-  try { if (!statSync(abs).isFile()) return null; } catch { return null; }
-  return abs;
+  let rp, rootReal;
+  try {
+    rp = realpathSync(abs);
+    rootReal = realpathSync(vaultPath);
+  } catch {
+    return null;
+  }
+  if (rp !== rootReal && !rp.startsWith(rootReal + sep)) return null;
+  try { if (!statSync(rp).isFile()) return null; } catch { return null; }
+  return rp;
 }

package/cli/rules/frontmatter-fields.js

@@ -1,9 +1,15 @@
 const BASE = ['title', 'created', 'updated', 'type', 'tags'];
 const SOURCE = ['source_url', 'ingested', 'sha256'];
-const DATE_RE = /^\d{4}-\d{2}-\d{2}/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const SHA_RE = /^[0-9a-f]{64}$/i;
 const STATES = new Set(['extracted', 'merged', 'inferred', 'ambiguous']);
 
+function validDate(v) {
+  if (!DATE_RE.test(v)) return false;
+  const d = new Date(v + 'T00:00:00Z'); // calendar check, timezone-stable
+  return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === v;
+}
+
 export const rule = {
   id: 'frontmatter.fields',
   run(model) {
@@ -18,7 +24,10 @@ export const rule = {
         hint: 'see schema/spec.md — Frontmatter' });
       const bad = [];
       for (const k of ['created', 'updated']) {
-        if (f.fm.fields[k] && !DATE_RE.test(f.fm.fields[k])) bad.push(`${k} is not an ISO date`);
+        if (f.fm.fields[k] && !validDate(f.fm.fields[k])) bad.push(`${k} is not a valid ISO date`);
+      }
+      if (isSource && f.fm.fields.ingested && !validDate(f.fm.fields.ingested)) {
+        bad.push('ingested is not a valid ISO date');
       }
       if (f.fm.fields.provenance_state && !STATES.has(f.fm.fields.provenance_state)) {
         bad.push(`provenance_state "${f.fm.fields.provenance_state}" is not one of extracted|merged|inferred|ambiguous`);

package/cli/rules/page-orphan.js

@@ -2,8 +2,13 @@ export const rule = {
   id: 'page.orphan',
   run(model) {
     const out = [];
+    const srcDir = model.config.sourceDir;
     for (const f of model.files) {
       if (!f.fm.ok) continue;
+      // raw/source pages quote their source — outbound links are not their job
+      const isSource = (model.config.inferredSkipTypes || []).includes(f.fm.fields.type)
+        || (srcDir && f.relPath.startsWith(`${srcDir}/`));
+      if (isSource) continue;
       const n = f.links.length;
       if (n < model.config.minOutboundLinks) out.push({ file: f.relPath, line: 1,
         message: `only ${n} outbound link(s) — orphaned page`,

package/cli/rules/placeholder-present.js

@@ -1,4 +1,7 @@
-const RE = /\b(TODO|TBD|FIXME|lorem ipsum)\b/i;
+// markers are case-sensitive conventions (TODO/FIXME/TBD) or colon-anchored;
+// bare lowercase "todo" in prose (Spanish "todo", domain terms like
+// "to-do list entity") is vocabulary, not a marker — see eval round 2b.
+const RE = null; // matching is inline in run() — kept for interface stability
 
 export const rule = {
   id: 'placeholder.present',
@@ -6,11 +9,23 @@ export const rule = {
     const out = [];
     for (const f of model.files) {
       const head = f.body.split('\n').slice(0, 20).join('\n');
-      const m = head.match(RE);
-      if (m) out.push({ file: f.relPath,
-        line: f.bodyStartLine + head.slice(0, m.index).split('\n').length - 1,
-        message: `placeholder text: ${m[0]}`,
-        hint: 'unfinished content erodes trust — finish or remove' });
+      for (const m of head.matchAll(/\b(TODO|FIXME|lorem ipsum|TBD)\b|\btodo\b/g)) {
+        const word = m[0];
+        const lower = word.toLowerCase();
+        const before = head.slice(Math.max(0, m.index - 2), m.index);
+        const after = head.slice(m.index + m[0].length, m.index + m[0].length + 2);
+        // markers: "TODO"/"FIXME" in caps, or any case followed by ":" —
+        // bare lowercase "todo" as a plain word (Spanish "todo", domain terms)
+        // is vocabulary, not a marker
+        const isMarker = word === 'TODO' || word === 'FIXME' || word === 'TBD'
+          || /[:：]\s*$/.test(after) || /^lorem/i.test(word);
+        if (!isMarker) continue;
+        out.push({ file: f.relPath,
+          line: f.bodyStartLine + head.slice(0, m.index).split('\n').length - 1,
+          message: `placeholder text: ${m[0]}`,
+          hint: 'unfinished content erodes trust — finish or remove' });
+        break; // one finding per file is enough to surface the pattern
+      }
     }
     return out;
   },

package/cli/rules/provenance-contradicted.js

@@ -9,7 +9,7 @@ export const rule = {
       const m = f.body.match(CALLOUT);
       const calloutTargets = m ? targetsIn(m[1]) : [];
       const fmList = (f.fm?.fields?.contradicted_by || '').replace(/[\[\]]/g, '');
-      const fmTargets = fmList ? fmList.split(',').map(s => s.trim()).filter(Boolean).map(t => t.replace(/\.md$/, '')) : [];
+      const fmTargets = fmList ? fmList.split(/[\s,]+/).map(s => s.trim()).filter(Boolean).map(t => t.replace(/\.md$/, '')) : [];
       if (m && !fmTargets.length) out.push({ file: f.relPath,
         line: f.bodyStartLine + f.body.slice(0, m.index).split('\n').length - 1,
         message: 'contradiction callout without contradicted_by in frontmatter',

package/cli/rules/provenance-excess-inferred.js

@@ -4,7 +4,10 @@ export const rule = {
     const out = [];
     for (const f of model.files) {
       if (!f.fm.ok) continue;
-      if (model.config.inferredSkipTypes.includes(f.fm.fields.type)) continue;
+      // exemption is location-based AND label-based: raw pages often lack the
+      // `source` type label, but living under sourceDir is dispositive
+      const underSourceDir = model.config.sourceDir && f.relPath.startsWith(`${model.config.sourceDir}/`);
+      if (model.config.inferredSkipTypes.includes(f.fm.fields.type) || underSourceDir) continue;
       const prose = f.paragraphs.filter(p => p.isProse && p.text);
       if (!prose.length) continue;
       // a paragraph counts as cited only when a citation sits on its final line

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustwiki",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.1",
   "description": "Provenance linter and method for agent-maintained knowledge bases — every claim cited, contradictions surfaced, rot detected.",
   "type": "module",
   "bin": {
@@ -24,8 +24,11 @@
     "proof"
   ],
   "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/QianJinGuo/trustwiki.git"
   }
-}
+}

package/templates/demo-vault/notes/conflict-a.md

@@ -10,4 +10,4 @@ tags: [demo]
 
 Tea should be brewed at 100°C.^[sources/tea.md]
 
-> [!contradiction] 参见 [[notes/conflict-b]] 持相反观点
+> [!contradiction] see [[notes/conflict-b]] which holds the opposite view

package/templates/eval-round3/a-vault/notes/agent-memory-options.md

@@ -0,0 +1,11 @@
+# Agent 记忆方案对比
+
+Agent 的跨会话记忆是目前 AI 工程的热点问题。没有记忆的 agent 每次对话都从零开始，无法积累对用户偏好和项目上下文的理解。
+
+目前主流的记忆方案分为两类：
+
+**文件式记忆**：把记忆存在 markdown 或文本文件中（如 CLAUDE.md、memory 目录）。优点是简单直接、可版本控制、人类可以直接查看和编辑。缺点是规模受限，当记忆量大了以后检索效率下降。
+
+**向量库记忆**：把记忆切分成 chunk 后存入向量数据库，通过语义相似度检索。优点是可扩展到大规模记忆、检索语义相关内容更准。缺点是引入了额外的基础设施、调试困难、机器可读但人类不友好。
+
+对于大多数团队，建议从文件式记忆起步，等规模需求出现后再引入向量检索。

package/templates/eval-round3/a-vault/notes/mcp-explained.md

@@ -0,0 +1,12 @@
+# MCP 是什么
+
+Model Context Protocol（MCP）是 AI 应用连接外部世界的通用标准。它就像 AI 应用的 USB-C 接口：过去每个 AI 应用要为每个数据源单独写集成，现在只需要接入 MCP，就能统一连接各种工具和数据。
+
+MCP 由 Anthropic 于 2024 年 11 月发布并开源。发布后迅速获得社区响应，成为 AI 工具生态中最受关注的协议之一。2025 年，OpenAI 和 Google DeepMind 相继宣布支持 MCP，这标志着 MCP 从单一公司的方案转变成了行业事实标准。
+
+MCP 的核心架构包含三种原语：
+- **Tools**：让 AI 可以调用外部函数，比如查询数据库、发送消息
+- **Resources**：让 AI 可以读取文件和数据
+- **Prompts**：预定义的提示模板
+
+MCP 的意义在于把 AI 应用从"信息孤岛"变成了"生态节点"。开发者不再需要为每个 AI 应用重复开发集成，工具开发者也只需要写一次 MCP server 就能服务所有支持的 AI 应用。

package/templates/eval-round3/a-vault/notes/memory-mcp-combo.md

@@ -0,0 +1,12 @@
+# 有记忆的 MCP Agent：两者如何组合
+
+MCP 解决了 agent 与外部工具的连接问题，记忆解决了 agent 跨会话的经验积累问题。两者结合，才能构成一个真正能长期服务的 agent。
+
+一个典型的组合架构：
+- 用 MCP 连接工具生态（数据库、API、文件系统）
+- 用文件式记忆保存用户的偏好、项目上下文、历史决策
+- 每次会话开始时，agent 先读取记忆文件恢复上下文，再通过 MCP 调用所需工具
+
+这种组合的优势在于关注点分离：MCP 管"能力"，记忆管"经验"。两者独立演进互不干扰。
+
+实践中需要注意的问题：记忆文件本身也会腐烂（过时信息、重复条目），需要定期整理。这是目前业界的普遍痛点。

package/templates/eval-round3/b-vault/.trustwiki.json

@@ -0,0 +1,5 @@
+{
+  "roots": ["notes", "sources"],
+  "index": "index.md",
+  "sourceDir": "sources"
+}

package/templates/eval-round3/b-vault/index.md

@@ -0,0 +1,7 @@
+# Team KB
+
+- [[notes/mcp-explained]] — MCP 是什么
+- [[notes/agent-memory-options]] — agent 记忆方案对比
+- [[notes/memory-mcp-combo]] — 有记忆的 MCP agent
+- [[sources/mcp-overview]] — 来源 1
+- [[sources/agent-memory-landscape]] — 来源 2

package/templates/eval-round3/b-vault/notes/agent-memory-options.md

@@ -0,0 +1,15 @@
+---
+title: Agent 记忆方案对比
+created: 2026-09-05
+updated: 2026-09-05
+type: note
+tags: [memory, agents]
+---
+
+Agent 跨会话记忆的两条主流路线：**文件式**（CLAUDE.md、memory 目录）与**向量库检索**。^[sources/agent-memory-landscape.md]
+
+文件式的核心优势是三重可审计：可版本控制（git 追溯每次变更）、人类可读（直接打开检查）、agent 友好（无需额外检索层）。代价是规模上限——记忆量大后检索效率下降。^[sources/agent-memory-landscape.md]
+
+向量库路线换取规模与语义召回，但引入基础设施与调试成本。值得注意 2026 年的趋势判断是**混合路线**：文件做索引层、向量做召回层。^[sources/agent-memory-landscape.md]
+
+决策启发：这不是二选一，而是先后问题。相关：[[mcp-explained]]、[[memory-mcp-combo]]。

package/templates/eval-round3/b-vault/notes/mcp-explained.md

@@ -0,0 +1,15 @@
+---
+title: MCP 是什么
+created: 2026-09-05
+updated: 2026-09-05
+type: note
+tags: [mcp, protocol]
+---
+
+MCP（Model Context Protocol）是 Anthropic 于 2024 年 11 月发布的开放协议，用 USB-C 类比其定位：统一 AI 应用与数据源之间的连接方式。^[sources/mcp-overview.md]
+
+2025 年 OpenAI 与 Google DeepMind 相继采纳后，MCP 从单公司方案转变为行业事实标准——这是判断它能否长期投入的关键信号。^[sources/mcp-overview.md]
+
+核心原语有三个：**tools**（可调用的外部函数）、**resources**（可读取的数据）、**prompts**（预定义模板）。理解三者的分工是设计 MCP 集成的基础。^[sources/mcp-overview.md]
+
+实践含义：团队选连接方案时，MCP 的事实标准地位意味着集成成本方向变了——过去是"为每个 AI 应用写一次集成"，现在收敛为"写一次 MCP server"。相关：[[agent-memory-options]]、[[memory-mcp-combo]]。

package/templates/eval-round3/b-vault/notes/memory-mcp-combo.md

@@ -0,0 +1,13 @@
+---
+title: 有记忆的 MCP Agent
+created: 2026-09-05
+updated: 2026-09-05
+type: note
+tags: [mcp, memory, architecture]
+---
+
+MCP 与记忆解决的是两个正交问题：MCP 管能力连接，记忆管经验积累。组合架构因此是关注点分离的，不是堆叠的。^[sources/mcp-overview.md] ^[sources/agent-memory-landscape.md]
+
+按来源给出的趋势判断，2026 年的组合形态是：文件式记忆做索引（保存偏好、项目上下文、历史决策），向量召回做扩展层，MCP 统一工具面。^[sources/agent-memory-landscape.md]
+
+一条来源没有展开、但工程师应该警惕的边界：记忆文件自身也会腐烂（过时条目、重复）。本知识库用 trustwiki 纪律对抗这个问题——这正是 Gate 阶段存在的理由（本句为工程推断，非来源内容）。^[sources/agent-memory-landscape.md] 相关：[[mcp-explained]]、[[agent-memory-options]]。

package/templates/eval-round3/b-vault/sources/agent-memory-landscape.md

@@ -0,0 +1,12 @@
+---
+title: Agent memory landscape (task source 2)
+created: 2026-09-05
+updated: 2026-09-05
+type: source
+tags: [memory, source]
+source_url: internal-task-brief
+ingested: 2026-09-05
+sha256: 8e735b918c7874b2e5a46580f06abfeffac2adaaffd265c0b85bc3d9004ae2d6
+---
+
+Agent 跨会话记忆：文件式（CLAUDE.md/memory 目录）vs 向量库检索。文件式可版本控制、人类可读、agent 友好；向量库适合大规模但引入基础设施。混合路线（文件索引+向量召回）为 2026 趋势判断。

package/templates/eval-round3/b-vault/sources/mcp-overview.md

@@ -0,0 +1,12 @@
+---
+title: MCP Overview (task source 1)
+created: 2026-09-05
+updated: 2026-09-05
+type: source
+tags: [mcp, source]
+source_url: internal-task-brief
+ingested: 2026-09-05
+sha256: 122a3aa6112694b91828b4a284e3badeb995fd797f6fdbce07f27c1d787e89d2
+---
+
+MCP: Anthropic 2024-11 发布的开放协议，USB-C 类比统一 AI 应用与数据源连接。2025 年 OpenAI、Google DeepMind 采纳，事实标准初步形成。核心原语：tools、resources、prompts。

package/templates/eval-round3/task.txt

@@ -0,0 +1,8 @@
+任务：为团队知识库创建三个主题页（notes/ 目录下），基于以下两份来源材料：
+1. 来源一（关于 MCP）：Model Context Protocol 是 Anthropic 2024 年 11 月发布的开放协议，
+   用 USB-C 类比统一 AI 应用与数据源之间的连接。2025 年被 OpenAI、Google DeepMind 采纳，
+   事实标准初步形成。核心原语：tools、resources、prompts。
+2. 来源二（关于 agent 记忆）：agent 跨会话记忆的主流方案是文件式记忆（如 CLAUDE.md、
+   memory 目录）与向量库检索两类。文件式可版本控制、人类可读、对 agent 友好；
+   向量库适合大规模但引入基础设施。混合路线（文件为索引+向量做召回）是 2026 年的趋势判断。
+要求：三页建议——「MCP 是什么」「agent 记忆方案对比」「两者如何组合：有记忆的 MCP agent」。