3zequiel3/chronicle

## 它是什么 获取任何项目并在 `knowledge-base/` 中生成一个**可导航且一致的知识库**，采用 **10 个规范槽位**（4 个始终存在的核心槽位 + 根据系统类型变化的可变槽位）：愿景、数据、规则、流、架构和决策。与一次性的生成器不同，它涵盖了**完整的生命周期**：生成、为现有代码编写文档、不破坏原有结构地进行更新以及审计。 ``` proyecto/ chronicle knowledge-base/ ├── docs/ ──────────► ┌──────────────┐ ──────► ├── 01_vision_y_objetivos.md ├── src/pagos/ │ 5 modos + │ ├── 04_modelos-apis/ ├── src/stock/ │ read-only │ ├── 05_reglas-de-negocio/ └── package.json └──────────────┘ └── 10_preguntas_abiertas.md ``` ## 从这里开始 1. **安装 skill** — 已发布在 **[skills.sh](https://www.skills.sh/3zequiel3/chronicle)**： npx skills add 3zequiel3/chronicle 2. **用自然语言提出需求** — 它在检测到意图时会自动激活： "documentá la funcionalidad de checkout" 3. **你将获得** `knowledge-base/` 中受影响的节点，每个论断都带有其**来源引用** (`[code · …]`)，完全不改动任何一行代码。 不知道你需要哪种模式？没关系：chronicle 会自动检测。 ## 5 种模式 **意图路由器** 通过低成本检测流程来选择模式： | 模式 | 何时使用 | 它的作用 | |------|--------|----------| | **A · Ingest** | 存在包含来源的 `docs/` | 仅通过**一个问题**（语言）生成完整的知识库；除此之外全自动执行。 | | **B · Scratch** | 没有文档和代码 | 充当**架构师 + 产品经理**：提问、提议、迭代。 | | **C · Reverse** | 存在未文档化的代码 | 通过阅读代码（只读）为**一项功能**编写文档。 | | **Update** | 已存在 `knowledge-base/` | **非破坏性合并**；对未更改的代码重新运行不会重写任何内容。 | | **Audit** | 你想验证知识库 | 报告完整性、一致性和 drift。**不生成，只审计。** | ``` # 调用示例 "creá la base de conocimiento del proyecto" → Mode A "armemos la KB desde cero" → Mode B "documentá la funcionalidad de checkout" → Mode C "actualizá la KB con la feature de devoluciones" → Mode Update "auditá la base de conocimiento" → Mode Audit ``` ## 黄金法则 任何无法证实的假设都会进入节点 `09`（推断的决策）或 `10`（开放性问题），绝不会作为事实记录在案。当记录已存在的内容时，chronicle 是**公证人**；而在尚未构建任何内容时，它仅仅是**顾问**。 并且，信任度不依赖于自觉性：每个引用都锚定到一个**真实的符号**，并且**机械检查**（git + regex + hash，无需 LLM）会将任何无法对应到代码的引用标记为缺陷 —— 它会在声明“完成”之前阻止关闭流程。因此，文档绝不会将系统实际所做的与某人假设其做的内容混为一谈。 ## 深入了解

📥 读取的来源（及其限制）

每个论断都标有来源。来源包括： - **代码** — 只读，引用锚定到符号（模式 C）。 - **文档** — `.txt`、`.docx`、`.pdf`、`.md`（模式 A）。 - **Manifests** — `package.json`、`go.mod`、`pyproject.toml`… 用于检测技术栈。 - **配置** — config keys、基于 config 的路由、`.env` → 节点 08。 - **Schema / DB** — 将 **schema 文件和迁移**（`prisma/schema.prisma`、`*.sql`、`openapi.*`）作为代码读取。**不连接到实际的数据库。** - **图表** — Mermaid/PlantUML/DOT 以及 **SVG/`.drawio`**（它们是文本/XML）：ERD → 节点 04，时序图 → 节点 07，架构图 → 节点 08。**光栅图像**（`.png`/`.jpg`）仅在 agent 具备视觉能力时才被读取，作为**低可信度**来源（它们会被放到节点 10 进行确认，绝不会作为已引用的事实）。

⚙️ 工作原理 — 检测流程

chronicle 以低成本启动，并且仅在必要时才提高成本。**情境是检测出来的；意图是询问出来的。** ``` Capa 0 · Huella del filesystem → stack (vía package.json/go.mod/…), dominios, (casi 0 tokens) tamaño y modo — SIN leer código fuente. Capa 1 · Confirmar + preguntar → muestra lo detectado y pregunta SOLO lo que ningún archivo puede saber (intención, trayectoria…). Capa 2 · Lectura profunda → solo en Mode C, y solo de la funcionalidad pedida. (acotada) ``` 这就是为什么为一个巨大的项目编写文档的成本几乎与一个小项目相同：它从不读取整个巨大的项目，只读取它的“足迹”和你要求的那一部分切片。

🗂️ 知识库结构

在所有项目中保持相同的形式 → 快速上手。节点 `09` (ADR) 强制记录每个决策的**原因**；而 `10` 则将**缺口明确化**，而不是将其掩盖。 **10 个规范槽位**分为两个正交的轴： - **核心 vs 可变**（存在哪些节点） — `01/02/09/10` 是核心（始终存在）；`03`-`08` 由系统类型的 *profile* 激活和构建。 - **映射 vs 集合**（文件 vs 文件夹） — **映射**（`01`、`02`、`03`、`08`、`10`）会被整体读取 → 单一文件；**集合**（`04`、`05`、`06`、`07`、`09`）会随着增长并按单元导航 → 根据大小选择单个文件或文件夹。 ``` knowledge-base/ ├── README.md # índice + resumen ejecutivo ├── 01_vision_y_objetivos.md # 🗺️ mapa ├── 02_descripcion_general.md # 🗺️ mapa — stack, arquitectura, integraciones ├── 03_actores_y_roles.md # 🗺️ mapa — RBAC, permisos ├── 04_modelos-apis/ # 📚 colección — modelos/ + contratos-api/ + ERD ├── 05_reglas-de-negocio/ # 📚 colección — un archivo por dominio (RN-XX) ├── 06_funcionalidades/ # 📚 colección — un archivo por épica (US-NNN) ├── 07_flujos-principales/ # 📚 colección — un archivo por flujo ├── 08_arquitectura_propuesta.md # 🗺️ mapa — patrones, seguridad, env vars ├── 09_decisiones/ # 📚 colección ADR — un archivo por decisión (DD-NN) └── 10_preguntas_abiertas.md # 🗺️ backlog — inconsistencias + dudas priorizadas ```

🎯 突出设计 — 按功能进行垂直切割

在模式 C 中，为“支付”编写文档会并行写入四个文件 —— 每个集合中一个 —— 遵循实际的流程，而不是代码的文件夹结构： ``` 04_modelos-apis/modelos/pago.md · 05_reglas-de-negocio/pagos.md 06_funcionalidades/pagos.md · 07_flujos-principales/pagos-checkout.md ``` 四个精确的 diffs，而不是四个被编辑的庞然大物。在合适的地方，节点使用原生的 Mermaid： ``` erDiagram USUARIO ||--o{ PEDIDO : crea PEDIDO ||--|{ ITEM : contiene PEDIDO }o--|| PAGO : tiene ```

🤖 Headless — 面向 orchestrator (SDD / CI)

orchestrator 构建的块看起来像这样： ``` chronicle.run: mode: update scope: { change_diff: ruta/al.patch, codes: [RN-RULES-02] } emit: { result: true } ``` 它**无需人工干预**运行（没有阻塞性的问题），返回一个结构化的 **result contract** + 可供机器导航的 manifest `index.json`，并在每次更改后**通过 delta 进行重新同步**（仅读取 diff 涉及的节点）。 - **幂等** — 对未更改的代码重新运行是一个无操作（空的 diff）。 - **Fail-closed** — 伪造的引用会阻塞 `ok`，绝不会表现为误报的通过。 - **新鲜度监控** — 一个可选的 hook 会在每次 commit 时通知哪些节点已过期（或仅触发同步）。 - **交互使用中无额外开销** — 只有当你进行编排时，才需要支付编排费用。 知识库作为 SDD/OpenSpec 类型流程的输入，而 `[MVP]`/`[Post-MVP]` 标签允许派生出 roadmap。

🗄️ .ledger/ — 工具状态和公共契约

`.ledger/` 位于项目的**根目录**，与 `knowledge-base/` 并列（不在其内部），并且被 **gitignored**：它是工具的本地状态，不进行版本控制 —— 一个全新的克隆会在首次运行时重新初始化它。它**仅由机械检查器写入**，绝不是由 LLM 手动写入。这样就不会出现“模型维护内存 JSON”的 drift：工具状态由工具负责。 **生成时间：** 在首次生成运行（模式 B/C）时播种，并在每次 *verify* 或 *staleness* 检查后刷新。不需要特意请求它：它是编写文档的副产品。 | 文件 | 存储内容 | 可见性 | |---------|-----------|---------| | `verification.json` | 每个声明的正确性验证状态 | 私有 | | `trace-map.json` | 用于解析 `code` 引用的 `file#symbol` 行 | 私有 | | `registry.json` | 仅追加的稳定 ID 账本 (RN-XX, DD-NN…) | 私有 | | `checks.json` | 检查器的配置 (含默认值) | 私有 | | **`fingerprints.json`** | **新鲜度映射 `path#symbol → { fingerprint, ref }`** | **公开** | **唯一公开的文件是 `fingerprints.json`** —— 这是一个配套的 skill（例如 **herald**）读取的投影，用于了解代码是否发生了变化，**而无需了解 chronicle 的内部机制**。这是它的确切形式（`version` 对其进行版本控制 —— 无法识别该版本的读取器不会解析它，而是重新生成它）： ``` { "version": 1, "ref": "", "fingerprints": { "src/payments/rules.ts#validateCoupon": { "fingerprint": "", "ref": "" } } } ``` **迁移（一次性，安全）：** 如果存在旧的 `knowledge-base/.chronicle/`，首次运行时会**复制 → 验证 → 清理**（绝不会盲目使用 `mv`）。如果迁移失败，它会继续读取旧版本（向下兼容），并且永远不会中断运行。

➕ 可选附加项

根据领域，chronicle 会添加前缀为 `1X_` 的额外节点，这些节点是**对 10 个规范节点的补充**，绝不替换它们： | 附加项 | 激活条件 | |-------|-------------------| | `12_seguridad_compliance.md` | 存在敏感数据 (PII, 支付) — 基于**数据类型**进行拦截 | | `13_glosario.md` | 适合固定领域的统一语言 | | `1X_tenancy.md` | 系统是 SaaS 多租户架构 |

🔄 更新 skill（对比更新知识库）

skill 是从 GitHub 拉取的副本；**它不会自动更新**： ``` npx skills update # actualiza todas las skills instaladas # o, puntual: npx skills add 3zequiel3/chronicle # re-instala = trae la última de main ```

## 贡献 欢迎 contributions。在进行 PR 之前，请开一个 issue 讨论重大的更改。skill 位于 `SKILL.md`（契约）和 `assets/`（按需加载的资源）中。 ## 许可证 [Apache-2.0](LICENSE) — 原创项目作者为 Ezequiel González。

标签：Homebrew安装, LNA, MITM代理, Ruby, SOC Prime, 开发工具, 文档生成, 知识库, 网络调试, 自动化, 自定义脚本, 防御加固