docs: log Jira Workflow Steward ingest completion

2026-04-30 00:48:06 +08:00
parent cbba7a4923
commit e1738bade1
6 changed files with 3165 additions and 1782 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,73 +1,74 @@
-# LLM Wiki Agent — Schema & Workflow Instructions
+# LLM Wiki Agent — 结构与工作流说明

-This wiki is maintained entirely by your coding agent. No API key or Python scripts needed — just open this repo in Codex, OpenCode, or any agent that reads this file, and talk to it.
+本 Wiki 完全由编码代理（agent）维护。无需 API Key 或 Python 脚本 —— 只需在 Codex、OpenCode 或任何能读取本文件的 agent 中打开此仓库，直接用自然语言交互即可。

-## How to Use
+## 使用方式

-Describe what you want in plain English:
- *"Ingest this file: raw/papers/my-paper.md"*
- *"What does the wiki say about transformer models?"*
- *"Check the wiki for orphan pages and contradictions"*
- *"Build the knowledge graph"*
+用自然语言描述你的需求：
+- *"摄取这个文件：raw/papers/my-paper.md"*
+- *"Wiki 里关于 transformer 模型说了什么？"*
+- *"检查 Wiki 中的孤立页面和冲突内容"*
+- *"构建知识图谱"*

-Or use shorthand triggers:
- `ingest <file>` → runs the Ingest Workflow
- `query: <question>` → runs the Query Workflow
- `lint` → runs the Lint Workflow
- `build graph` → runs the Graph Workflow
+或使用快捷触发词：
+- `ingest <file>` → 执行摄取工作流
+- `query: <问题>` → 执行查询工作流
+- `lint` → 执行检查工作流
+- `build graph` → 执行图谱构建工作流

 ---

-## Directory Layout
+## 目录结构

 ```
-raw/          # Immutable source documents — never modify these
-wiki/         # Agent owns this layer entirely
-  index.md    # Catalog of all pages — update on every ingest
-  log.md      # Append-only chronological record
-  overview.md # Living synthesis across all sources
-  sources/    # One summary page per source document
-  entities/   # People, companies, projects, products
-  concepts/   # Ideas, frameworks, methods, theories
-  syntheses/  # Saved query answers
-graph/        # Auto-generated graph data
-tools/        # Optional standalone Python scripts (require ANTHROPIC_API_KEY)
+raw/          # 不可变的原始文档 —— 永远不要修改这里的内容
+wiki/         # Agent 完全负责维护的知识层
+  index.md    # 所有页面的目录 —— 每次摄取后必须更新
+  log.md      # 只追加的时间线记录
+  overview.md # 跨所有来源的动态综合摘要
+  sources/    # 每个原始文档对应一个摘要页
+  entities/   # 人物、公司、项目、产品
+  concepts/   # 想法、框架、方法、理论
+  syntheses/  # 保存的查询答案
+graph/        # 自动生成的图谱数据
+tools/        # 可选的独立 Python 脚本（需要 ANTHROPIC_API_KEY）
 ```

 ---

-## Page Format
+## 页面格式

-Every wiki page uses this frontmatter:
+每个 Wiki 页面都使用以下 frontmatter：

 ```yaml
 ---
-title: "Page Title"
+title: "页面标题"
 type: source | entity | concept | synthesis
 tags: []
-sources: []       # list of source slugs that inform this page
+sources: []       # 支撑本页面的来源 slug 列表
 last_updated: YYYY-MM-DD
 ---
 ```

-Use `[[PageName]]` wikilinks to link to other wiki pages.
+使用 `[[页面名]]` 格式的 wikilink 链接到其他 Wiki 页面。

 ---

-## Ingest Workflow
+## 摄取工作流（Ingest Workflow）

-Triggered by: *"ingest <file>"*
+触发方式：*"ingest <file>"*

-Steps (in order):
-1. Read the source document fully
-2. Read `wiki/index.md` and `wiki/overview.md` for current wiki context
-3. Write `wiki/sources/<slug>.md` — use the source page format below
-4. Update `wiki/index.md` — add entry under Sources section
-5. Update `wiki/overview.md` — revise synthesis if warranted
-6. Update/create entity pages for key people, companies, projects mentioned
-7. Update/create concept pages for key ideas and frameworks discussed
-8. Flag any contradictions with existing wiki content
-9. Append to `wiki/log.md`: `## [YYYY-MM-DD] ingest | <Title>`
+### 执行步骤（严格顺序）
+
+1. 使用 Read 工具完整读取待摄取的source文档
+2. 读取 `wiki/index.md` 和 `wiki/overview.md`，了解当前 Wiki 上下文
+3. 生成 `wiki/sources/<slug>.md`（严格参照下方 Source Page Format）
+4. 更新 `wiki/index.md`，在 Sources 节添加新条目（参照下方 Index 格式）
+5. 更新 `wiki/overview.md`（如有必要则修订综合摘要）
+6. 创建或更新提及的关键人物、公司、项目对应的 Entity 页面（参照下方 Entity（实体））
+7. 创建或更新讨论的关键想法和框架对应的 Concept 页面（参照下方 Concept（概念））
+8. 检测并记录与现有 Wiki 内容的冲突
+9. 追加 `wiki/log.md`（参照下方 Log Format（日志格式））

 ### Source Page Format

@@ -77,143 +78,174 @@ title: "Source Title"
 type: source
 tags: []
 date: YYYY-MM-DD
-source_file: raw/...
 ---

-## Summary
-2–4 sentence summary.
+## Source File
+- [[{{ $json.file.rel_path }}]]

-## Key Claims
- Claim 1
- Claim 2
+## Summary（用中文描述）
+- 核心主题：
+- 问题域：
+- 方法/机制：
+- 结论/价值：
+
+## Key Claims（用中文描述）
+- （必须符合：主体 + 机制 + 结果）

 ## Key Quotes
-> "Quote here" — context
+> "引用内容" — 上下文说明
+
+## Key Concepts
+- [[ConceptName]]：定义
+
+## Key Entities
+- [[EntityName]]：角色说明

 ## Connections
- [[EntityName]] — how they relate
- [[ConceptName]] — how it connects
+- [[A]] ← depends_on ← [[B]]
+- [[C]] ← extends ← [[D]]

 ## Contradictions
- Contradicts [[OtherPage]] on: ...
+- 与 [[OtherPage]] 冲突：
+  - 冲突点：
+  - 当前观点：
+  - 对方观点：
 ```
+---

-### Domain-Specific Templates
+## Entity 与 Concept 规则

-If the source falls into a specific domain (e.g., personal diary, meeting notes), the agent should use a specialized template instead of the default generic one above:
+### Entity（实体）
+
+**创建条件：**
+- 出现 ≥ 2 次，或
+- 对主题有关键影响
+
+**类型：** 人 / 公司 / 产品 / 项目
+
+---
+
+### Concept（概念）
+
+**创建条件：**
+- 可抽象
+- 可复用
+- 非具体实例
+
+---
+
+### 命名规范（强制）
+
+- 使用唯一标准名称
+- 所有别名写入页面：

-#### Diary / Journal Template
 ```markdown
---
-title: "YYYY-MM-DD Diary"
-type: source
-tags: [diary]
-date: YYYY-MM-DD
---
-## Event Summary
-...
-## Key Decisions
-...
-## Energy & Mood
-...
-## Connections
-...
-## Shifts & Contradictions
-...
-```
-
-#### Meeting Notes Template
-```markdown
---
-title: "Meeting Title"
-type: source
-tags: [meeting]
-date: YYYY-MM-DD
---
-## Goal
-...
-## Key Discussions
-...
-## Decisions Made
-...
-## Action Items
-...
+## Aliases
+- GPT4
+- GPT-4
 ```

 ---

-## Query Workflow
+### 去重机制（必须）

-Triggered by: *"query: <question>"*
-
-Steps:
-1. Read `wiki/index.md` to identify relevant pages
-2. Read those pages
-3. Synthesize an answer with inline citations as `[[PageName]]` wikilinks
-4. Ask the user if they want the answer filed as `wiki/syntheses/<slug>.md`
+创建前必须：
+1. 搜索 index
+2. 判断是否已存在同名/近义页面
+3. 存在则更新，不存在再新建

 ---

-## Lint Workflow
+## 查询工作流（Query Workflow）

-Triggered by: *"lint"*
+触发方式：*"query: <问题>"*

-Check for:
- **Orphan pages** — wiki pages with no inbound `[[links]]` from other pages
- **Broken links** — `[[WikiLinks]]` pointing to pages that don't exist
- **Contradictions** — claims that conflict across pages
- **Stale summaries** — pages not updated after newer sources
- **Missing entity pages** — entities mentioned in 3+ pages but lacking their own page
- **Data gaps** — questions the wiki can't answer; suggest new sources
-
-Output a lint report and ask if the user wants it saved to `wiki/lint-report.md`.
+步骤：
+1. 读取 `wiki/index.md`，确定相关页面
+2. 读取这些页面的内容
+3. 综合生成答案，并以 `[[页面名]]` wikilink 形式内联引用来源
+4. 询问用户是否将答案保存为 `wiki/syntheses/<slug>.md`

 ---

-## Graph Workflow
+## 检查工作流（Lint Workflow）

-Triggered by: *"build graph"*
+触发方式：*"lint"*

-First try: `python tools/build_graph.py --open`
+检查项目：
+- **孤立页面** —— 没有任何其他页面通过 `[[links]]` 指向它的 Wiki 页面
+- **断链** —— `[[WikiLinks]]` 指向不存在的页面
+- **内容冲突** —— 跨页面存在相互矛盾的论点
+- **过时摘要** —— 有更新来源后未同步更新的页面
+- **缺失 Entity 页面** —— 在 3 个以上页面中被提及但没有独立页面的实体
+- **数据缺口** —— Wiki 无法回答的问题，建议补充新来源

-If Python/deps unavailable, build manually:
-1. Search for all `[[wikilinks]]` across wiki pages
-2. Build nodes (one per page) and edges (one per link)
-3. Infer implicit relationships not captured by wikilinks — tag `INFERRED` with confidence score; low confidence → `AMBIGUOUS`
-4. Write `graph/graph.json` with `{nodes, edges, built: date}`
-5. Write `graph/graph.html` as a self-contained vis.js visualization
+输出检查报告，并询问用户是否保存为 `wiki/lint-report.md`。

 ---

-## Naming Conventions
+## 图谱构建工作流（Graph Workflow）

- Source slugs: `kebab-case` matching source filename
- Entity pages: `TitleCase.md` (e.g. `OpenAI.md`, `SamAltman.md`)
- Concept pages: `TitleCase.md` (e.g. `ReinforcementLearning.md`, `RAG.md`)
+触发方式：*"build graph"*

-## Index Format
+优先尝试：`python tools/build_graph.py --open`
+
+若 Python/依赖不可用，则手动构建：
+1. 搜索所有 Wiki 页面中的 `[[wikilinks]]`
+2. 构建节点（每页一个）和边（每个链接一条）
+3. 推断 wikilink 未捕获的隐式关系 —— 标记为 `INFERRED` 并附置信度；低置信度 → `AMBIGUOUS`
+4. 写入 `graph/graph.json`，格式：`{nodes, edges, built: date}`
+5. 写入 `graph/graph.html`，作为独立的 vis.js 可视化文件
+
+---
+
+## 命名规范
+
+- Source slug：`kebab-case`，与源文件名保持一致
+- Entity 页面：`TitleCase.md`（如 `OpenAI.md`、`SamAltman.md`）
+- Concept 页面：`TitleCase.md`（如 `ReinforcementLearning.md`、`RAG.md`）
+
+## Index 格式

 ```markdown
 # Wiki Index

 ## Overview
- [Overview](overview.md) — living synthesis
+- [Overview](overview.md) — 动态综合摘要

 ## Sources
- [Source Title](sources/slug.md) — one-line summary
+- [来源标题](sources/slug.md) — 一行摘要

 ## Entities
- [Entity Name](entities/EntityName.md) — one-line description
+- [实体名称](entities/EntityName.md) — 一行描述

 ## Concepts
- [Concept Name](concepts/ConceptName.md) — one-line description
+- [概念名称](concepts/ConceptName.md) — 一行描述

 ## Syntheses
- [Analysis Title](syntheses/slug.md) — what question it answers
+- [分析标题](syntheses/slug.md) — 回答了什么问题
 ```

-## Log Format
+## Log Format（日志格式）

-`## [YYYY-MM-DD] <operation> | <title>`
+```
+## [YYYY-MM-DD] ingest | 标题
+- Source file: {{ $json.file.rel_path }}
+- Status: ✅ 成功摄入
+- Summary:
+- Concepts created: xxx, xxx
+- Source page: {{ $json.file.source_path }}
+- Notes:
+```

-Operations: `ingest`, `query`, `lint`, `graph`
+操作类型：`ingest`、`query`、`lint`、`graph`
+
+---
+
+## 最终目标
+
+该系统用于：
+- 知识沉淀
+- 结构化理解
+- 自动图谱构建
+- Agent 推理支持