@riconext/hermes-repo 0.15.1 → 1.0.0

package/dist/templates/AGENTS.hermes-block.tpl

@@ -1,119 +1,6 @@
-## 记忆系统
+# 项目指令
 
-本项目使用 @riconext/hermes-repo 管理 AI 助手记忆。
 
-核心文件:
-
-- `.memory/MEMORY.md` — 注入到每次会话的摘要
-- `.memory/captures/` — 按类型（semantic / episodic / procedural）归档的原始捕获
-- `.memory/topics/` — 整理后的主题记忆
-
-## 使用记忆
-
-- 开始新任务前，先读取 `.memory/MEMORY.md`
-- 如需查找历史经验: `npx @riconext/hermes-repo search <关键词>`
-- 查看特定捕获: `cat .memory/captures/<type>/<文件名>.md`
-- 查看主题: `cat .memory/topics/<主题>.md`
-- 查看可用技能: `cat .memory/skills/*/SKILL.md`
-
-## 技能使用
-
-项目自动从重复的流程记忆中生成技能（SKILL.md），存在 `.memory/skills/`。
-
-### 何时加载技能
-
-当你需要执行以下操作时，先查看是否有对应的技能:
-
-1. 部署 / 发布 / 回滚
-2. 数据库迁移
-3. 新模块 / 新页面创建
-4. 重复性配置操作
-5. 调试已知类型的问题
-
-### 如何使用
-
-1. 查看技能目录: `ls .memory/skills/`
-2. 匹配到任务后: `cat .memory/skills/<name>/SKILL.md`
-3. 按步骤执行
-4. 执行结束后，在捕获中引用技能名（帮助 consolidate 追踪技能有效性）
-
-## 何时搜索过去经验
-
-当你遇到以下情况，应主动搜索 `.memory/` 中的历史记忆:
-
-1. 处理你之前解决过类似问题的模块
-2. 需要进行与上次类似的技术选型
-3. 用户说「之前不是这样」或「上次讨论过」
-4. 需要了解项目的历史架构决策
-
-## 记录新经验
-
-当你遇到以下情况，在 `.memory/captures/` 创建捕获文件:
-
-1. 你犯了错误并被用户纠正
-2. 你发现代码与已有约定不一致
-3. 你了解到项目特有的架构决策（包括被否决的方案）
-4. 你做出了非平凡的设计选择（包括为什么选 A 不选 B）
-5. 你重复遇到了类似问题（说明前一次的经验没有被记住）
-6. 你完成了复杂的多步操作流程
-
-### 分类参考
-
-- **语义记忆**: 事实、约定、决策原则 → type: semantic
-- **情景记忆**: 具体事件经过 → type: episodic
-- **流程记忆**: 操作步骤 → type: procedural
-
-### scope 选择
-
-- 这个经验适用于整个项目吗？→ scope: all
-- 只适用于前端 / 后端 / 基础设施？→ 对应 scope
-
-## 团队协作（多人仓库）
-
-本项目由多人维护。记忆分两层:
-
-### 个人层（仅你自己可见，不提交 git）
-
-- `.memory/captures/` — 你这次的 AI 捕获
-- `.memory/refs/` — 你的引用记录
-- 不需要审批，直接写入
-
-### 团队层（所有人可见，提交 git）
-
-- `.memory/topics/` — 团队认同的约定
-- `.memory/skills/` — 团队可复用的技能
-- `.memory/MEMORY.md` — 团队记忆摘要
-
-### 晋升团队层
-
-当你觉得某条个人捕获对团队有价值:
-
-1. 标记晋升: `touch .memory/captures/<type>/xxx.promote`
-2. 使用 PR 模板 `.memory/templates/PROMOTE_PR.md` 创建晋升 PR
-3. 等团队 review 后合并；`promote --pr` 生成草案，`promote --apply --manifest` 落盘（v0.13+）
-
-### 冲突处理
-
-如果发现团队层记忆与你的经验矛盾:
-
-1. 在 `.memory/team/conflict-resolutions/` 创建冲突记录
-2. 不要直接修改团队层文件
-3. 在 PR 或周会上提出讨论
-
-## 引用记录
-
-当你读取某条捕获或技能后，记录引用（供 flush 聚合 `use_count`）:
-
-```bash
-npx @riconext/hermes-repo ref --capture captures/semantic/<文件>.md --reason "为何查看"
-npx @riconext/hermes-repo ref --skill <slug> --reason "执行前加载技能"
-```
-
-也可在 `.memory/refs/` 手写 JSON（`target` 为相对 `.memory/` 的路径）。
-
-## 禁止
-
-- 不要写入代码的具体实现细节（代码本身是自文档的）
-- 不要写入敏感信息（密钥、密码、个人数据）
-- 不要重复写入已存在的内容（先搜索再写）
-- 不要在没有用户交互的会话中创建捕获（纯自动化操作不产生经验）
+<!-- >>> hermes-repo agents (do not edit this block manually) -->
+__HERMES_AGENTS_BLOCK__
+<!-- <<< hermes-repo agents -->

package/dist/templates/AGENTS.md.tpl

@@ -1,6 +1,130 @@
-# 项目指令
+# Hermes 记忆系统指南
 
+> 本文档由 `hermes init` 自动生成。如需更新记忆结构，运行 `hermes init --force`。
 
-<!-- >>> hermes-repo agents (do not edit this block manually) -->
-__HERMES_AGENTS_BLOCK__
-<!-- <<< hermes-repo agents -->
+## 核心概念
+
+本项目使用 **hermes-repo** 管理 AI 编程助手的项目级记忆系统。
+
+**设计原则：**
+- **Captures 是 raw evidence** — 对话记录自动保存到 `captures/raw/`，不等于知识
+- **LLM 提炼后进入知识库** — 手动 `hermes flush` 触发 consolidate，由 LLM 整理成结构化知识
+- **按业务域组织** — 改库存读 `domains/inventory/`，改报价读 `domains/quoted/`
+- **两阶段注入** — 启动时先加载导航+规则全文，AI 按需读取具体域知识
+
+## 目录结构
+
+```
+.memory/
+├── MEMORY.md              # ← 导航中心（自动生成 + 可手动编辑）
+├── config.json            # 配置（含 LLM 设置）
+│
+├── rules/                 # 必读规则（编码规范、约定）
+├── domains/{domain}/      # 业务域知识（LLM 自动分类）
+│   └── general/           # 兜底域
+├── workflows/             # 可复用操作流程
+├── decisions/             # 历史决策记录
+├── incidents/             # 踩坑记录
+│
+└── captures/
+    ├── raw/               # 原始对话记录（gitignored）
+    └── archived/          # 已归档的旧记录
+```
+
+## Inject（启动时自动加载）
+
+每次 AI 会话开始时，hook 会自动调用 `hermes inject`：
+
+**注入内容：**
+1. `MEMORY.md` 导航摘要（所有知识的索引）
+2. `rules/` 目录下全部文件的完整内容（必读规则）
+
+**AI 应该怎么做：**
+- 先阅读 MEMORY.md 了解项目全貌和可用知识
+- 遵守 rules/ 中列出的所有编码规范
+- 根据任务判断需要哪个业务域的知识 → 用工具读取对应文件：
+  ```bash
+  cat .memory/domains/{domain}/{file}.md
+  cat .memory/workflows/{file}.md
+  ```
+
+## Capture（结束时自动保存）
+
+对话结束时，hook 会自动调用 `hermes capture`：
+
+- 所有对话内容保存到 `captures/raw/session-{id}.md`
+- 一个对话一个文件，支持追加
+- **无需手动创建捕获** — 系统自动处理
+
+## Consolidate（手动触发提炼）
+
+当积累了足够的对话记录后，手动执行：
+
+```bash
+npx @riconext/hermes-repo flush
+```
+
+这会：
+1. 扫描所有待处理的 session 文件（pending / stale）
+2. 单次 LLM 调用完成完整提炼：
+   - 域提取 → 分类判定 → 内容提炼 → 导航生成
+3. 输出写入 `rules/`, `domains/`, `workflows/`, `decisions/`, `incidents/`
+4. 更新 `MEMORY.md` 导航
+5. 将已处理的 session 标记为 done
+
+**前提条件：**
+- 需要配置 LLM（见下方配置说明）
+
+## 配置 LLM
+
+在 `.memory/config.json` 中配置：
+
+```json
+{
+  "llm": {
+    "enabled": true,
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "gpt-4o"
+  }
+}
+```
+
+API Key 通过环境变量设置：
+```bash
+export HERMES_LLM_API_KEY="sk-..."
+```
+
+## 常用命令
+
+| 命令 | 用途 |
+|------|------|
+| `hermes init` | 初始化记忆脚手架 |
+| `hermes inject` | 注入上下文（通常由 hook 自动调用） |
+| `hermes capture` | 保存对话记录（通常由 hook 自动调用） |
+| `hermes flush` | 触发 LLM consolidate（手动） |
+
+## 知识类型
+
+consolidate 时 LLM 会将内容分为 5 类：
+
+| 类型 | 存放位置 | 说明 |
+|------|---------|------|
+| rule | `rules/` | 编码规范、团队约定、禁令 |
+| domain-knowledge | `domains/{domain}/` | 业务事实、数据模型、领域逻辑 |
+| workflow | `workflows/` | 可复用操作步骤流程 |
+| decision | `decisions/` | 架构选型及原因 |
+| incident | `incidents/` | 踩坑记录、问题根因、修复方式 |
+
+每条知识都有状态字段：`active` | `implemented` | `superseded` | `needs_review` | `archived`
+
+## 编辑约定
+
+- **MEMORY.md 可以手动编辑** — 用 `<!-- user-edit-start --> ... <!-- user-edit-end -->` 包裹自定义区域，flush 时保留
+- **Knowledge 文件可以手动编辑** — 直接修改 markdown 内容即可
+- **不要直接编辑 captures/raw/ 中的文件** — 这些是自动生成的原始记录
+
+## 禁止事项
+
+- 不要写入代码的具体实现细节（代码本身是自文档的）
+- 不要写入敏感信息（密钥、密码、个人数据）
+- 不要重复写入已存在的内容（先搜索再写）

package/dist/templates/MEMORY.md.tpl

@@ -1,25 +1,43 @@
-# 项目记忆
+# 项目知识库
 
-最后更新: — | 总计: 0 条捕获（0 语义 + 0 情景 + 0 流程）
+最后更新: — | 域: 0 | 规则: 0 | 工作流: 0 | 决策: 0 | 踩坑: 0
 
-## 活跃主题
+> 此文件由 `hermes flush` 后 LLM 自动生成，也可手动编辑。
+> 编辑时请保留 <!-- user-edit-start --> ... <!-- user-edit-end --> 标记。
 
-（consolidate 后自动填充）
+## 必读规则
 
-## 最近经验
+> 每次会话都应加载的编码规范和项目约定
 
 （consolidate 后自动填充）
 
-## 项目约定
+## 业务域
 
-（consolidate 后自动填充）
+> 根据任务选择相关域读取
+
+| 域 | 文件 | 摘要 |
+|----|------|------|
+| — | — | — |
+
+（首次 `hermes flush` 后自动生成）
+
+## 工作流
+
+> 可复用的执行流程
+
+（consolidate 后从 procedural captures 晋升填充）
+
+## 决策 & 踩坑
+
+> 需要了解背景时按需查看
 
-## 可用技能
+- decisions/: 0 条记录
+- incidents/: 0 条记录
 
-（consolidate 后从 procedural 晋升填充）
+---
 
-## 检索提示
+## 使用说明
 
-- 手动整理记忆: `npx @riconext/hermes-repo flush`
-- 查看捕获: `ls .memory/captures/` 或 `cat .memory/captures/<type>/<文件>.md`
-- 查看主题: `ls .memory/topics/`
+- 整理记忆（触发 consolidate）: `npx @riconext/hermes-repo flush`
+- 查看原始捕获: `ls .memory/captures/raw/`
+- 查看业务域: `ls .memory/domains/`

package/dist/templates/capture-session.example.md

@@ -0,0 +1,26 @@
+---
+sessionId: example-session-id
+source: session
+status: pending
+domain: null
+createdAt: 2026-06-23T16:00:00
+lastModifiedAt: 2026-06-23T16:00:00
+consolidatedAt: null
+captureCount: 2
+---
+
+## Capture #1 — 16:00:00
+### type: semantic
+### tags: ["discount","quoted"]
+
+讨论了报价单的 discount 显示逻辑：
+- 折扣字段来自后端 API `/api/quoted/discount`
+- 前端展示需要乘以汇率
+- 注意：折扣百分比需要除以 100 后展示
+
+## Capture #2 — 16:15:00
+### type: episodic
+### tags: ["bug-fix"]
+
+因为 discount 字段没有做空值判断，导致部分报价单页面白屏。
+修复方案：在渲染前加 `?? 0` 兜底。

package/dist/templates/config.json.tpl

@@ -1,8 +1 @@
-{
-  "version": 1,
-  "storage": {
-    "backend": "file"
-  },
-  "assistants": ["claude-code"],
-  "debug": false
-}
+{"version": 2, "storage": {"backend": "file"}, "assistants": ["claude-code"], "debug": false, "llm": {"enabled": false, "baseUrl": "https://api.openai.com/v1", "model": "gpt-4o"}, "consolidate": {"autoArchiveDays": 30}}

package/dist/templates/gitignore-block.txt

@@ -1,22 +1,15 @@
 # >>> hermes-repo memory (do not edit this block manually)
-# 个人层 — 不提交
+# 不提交（个人数据 / 运行时状态）
 .memory/captures/
-.memory/llm.json
-.memory/sessions/
-.memory/refs/
-.memory/personal/
-.memory/hermes-debug.log
 .memory/consolidate-state.json
 .memory/.consolidate.lock
-.memory/skill-usage.json
-.memory/promote/
 
-# 团队层 — 提交
-!.memory/topics/
-!.memory/skills/
+# 提交到 Git（团队共享的知识）
 !.memory/MEMORY.md
-!.memory/MEMORY-*.md
-!.memory/team/
 !.memory/config.json
-!.memory/templates/
+!.memory/rules/
+!.memory/domains/
+!.memory/workflows/
+!.memory/decisions/
+!.memory/incidents/
 # <<< hermes-repo memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riconext/hermes-repo",
-  "version": "0.15.1",
+  "version": "1.0.0",
   "description": "跨编程助手的项目级记忆系统",
   "packageManager": "bun@1.3.12",
   "type": "module",

package/dist/templates/PROMOTE_PR.md

@@ -1,21 +0,0 @@
-## 记忆晋升申请
-
-### 自动扫描结果
-
-本次检测到 {total_count} 条 promoted capture，建议晋升 {ai_approve_count} 条到团队层。
-
----
-
-<!-- 由 `npx @riconext/hermes-repo promote --pr` 自动填充每条捕获 -->
-
-### 操作说明
-
-1. 每一条勾选一个选项
-2. 如需说明，在对应项后附言
-3. 提交 review → 根据勾选结果执行 `promote --apply`
-
-### 本次晋升总览
-
-| 序号 | 摘要 | AI 建议 | scope |
-|------|------|---------|-------|
-| — | — | — | — |

package/dist/templates/SKILL.md.tpl

@@ -1,23 +0,0 @@
----
-name: example-skill
-description: >
-  （技能简短描述：何时激活、解决什么问题）
-version: 1.0.0
-author: @riconext/hermes-repo
-platforms: [linux, macos]
-trigger-tags: [workflow]
-created-from:
-  - captures/procedural/capture-example.md
----
-
-## 步骤
-
-1. （步骤一）
-
-## 常见陷阱
-
-- （易错点）
-
-## 验证
-
-- （如何确认成功）

package/dist/templates/capture-episodic.example.md

@@ -1,20 +0,0 @@
----
-type: episodic
-date: 2026-05-20
-session: example-session-id
-tags: [debugging, incident]
-scope: all
-confidence: pending
----
-
-## 上下文
-
-（具体事件背景）
-
-## 经过
-
-（发生了什么、采取了什么措施）
-
-## 结果
-
-（最终结果与教训）

package/dist/templates/capture-procedural.example.md

@@ -1,27 +0,0 @@
----
-type: procedural
-date: 2026-05-20
-session: example-session-id
-tags: [deploy, workflow]
-scope: all
-step_count: 0
-repeat_count: 1
-confidence: pending
----
-
-## 目标
-
-（要完成什么）
-
-## 步骤
-
-1. （步骤一）
-2. （步骤二）
-
-## 注意
-
-（易错点、前置条件）
-
-## 验证
-
-（如何确认成功）

package/dist/templates/capture-semantic.example.md

@@ -1,20 +0,0 @@
----
-type: semantic
-date: 2026-05-20
-session: example-session-id
-tags: [auth, token, security]
-scope: all
-confidence: pending
----
-
-## 上下文
-
-（描述当时正在做什么）
-
-## 发现
-
-（项目事实、约定或架构决策）
-
-## 影响
-
-（对后续开发的影响，可选）

package/dist/templates/llm.json.example

@@ -1,10 +0,0 @@
-{
-  "enabled": false,
-  "provider": "openai",
-  "baseUrl": "https://api.deepseek.com",
-  "model": "deepseek-v4-flash",
-  "apiKey": "",
-  "timeoutMs": 60000,
-  "maxInputChars": 24000,
-  "mode": "async"
-}

package/dist/templates/steward-log.md.tpl

@@ -1,6 +0,0 @@
-# Memory Steward 日志
-
-记录团队记忆维护轮值与重要操作。
-
-| 日期 | 负责人 | 操作 |
-|------|--------|------|