@codehourra/llm-iwiki 0.2.1 → 0.3.0

package/README.md

@@ -1,77 +1,146 @@
 # llm-iwiki
 
-面向 AI Agent 的本地知识库 CLI。
+[简体中文](./README.zh-CN.md)
 
-`llm-iwiki` 会采集 Claude Code、Cursor、Codex、CodeBuddy 等 AI 编程工具的本地会话记录，按项目归一化到 SQLite，再通过 AI 工具生成结构化 YAML 摘要和经验候选，最终导出到 Obsidian。
+[![npm version](https://img.shields.io/npm/v/@codehourra/llm-iwiki.svg)](https://www.npmjs.com/package/@codehourra/llm-iwiki)
+[![npm downloads](https://img.shields.io/npm/dm/@codehourra/llm-iwiki.svg)](https://www.npmjs.com/package/@codehourra/llm-iwiki)
+[![Node.js](https://img.shields.io/node/v/@codehourra/llm-iwiki.svg)](https://www.npmjs.com/package/@codehourra/llm-iwiki)
+[![Release](https://github.com/CodeHourra/llm-iwiki/actions/workflows/release.yml/badge.svg)](https://github.com/CodeHourra/llm-iwiki/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Changelog](https://img.shields.io/badge/changelog-CHANGELOG.md-blue)](./CHANGELOG.md)
 
-## 安装
+Turn local AI coding sessions into a searchable Obsidian knowledge base.
 
-> 运行时只需 [Node.js](https://nodejs.org) ≥ 20（无需 Bun）。SQLite 通过原生模块 `better-sqlite3` 提供，`npm install` 时自动下载预编译二进制。
+`llm-iwiki` collects sessions from Claude Code, Cursor, Codex, Gemini, and CodeBuddy, normalizes them by project in SQLite, prepares AI-friendly summarization tasks, stores accepted project learnings, and exports navigable Markdown notes to Obsidian.
+
+## Features
+
+- Collect local AI coding sessions across multiple tools.
+- Resolve sessions by project, repository, path, or slug.
+- Generate summarization and experience-extraction task files for AI assistants.
+- Review and accept reusable engineering experiences before publishing them.
+- Export project summaries, session notes, and project-scoped experiences to Obsidian.
+- Preserve user-written note sections while updating managed content blocks.
+- Search session summaries and accepted experiences from the CLI.
+
+## Requirements
+
+- Node.js 20 or newer at runtime.
+- Bun for local development, testing, and building.
+
+SQLite is provided by `better-sqlite3`; prebuilt binaries are installed automatically by npm where available.
+
+## Installation
 
 ```bash
-# 全局安装
 npm install -g @codehourra/llm-iwiki
-
-llm-iwiki init      # 初始化配置与状态库
-llm-iwiki doctor    # 自检
 ```
 
-也可以免安装、用 `npx` 直接运行：
+You can also run it without installing globally:
 
 ```bash
-npx @codehourra/llm-iwiki init
-npx @codehourra/llm-iwiki sync
+npx @codehourra/llm-iwiki --help
 ```
 
-## 当前状态
+## Quick Start
 
-- Milestone 1（CLI 骨架与状态库）已完成：`init` / `doctor` / `projects resolve` / `projects rename`。
-- Milestone 2（Collectors）基本完成：已实现 **Claude Code / Codex / Cursor / Gemini / CodeBuddy** 五个 collector 与 `sync`，可把本地会话按项目归一化入库，并通过 `projects list` / `projects inspect` 按项目维度跨工具聚合查看。
-- Milestone 4（AI 协作总结）已完成：`summarize prepare` / `experiences prepare` 生成压缩后的 AI 任务，`summarize apply` / `experiences propose` 把外部 AI 产出的 YAML 落库到 `session_summaries` / `experience_candidates`。
-- Milestone 5（Obsidian 导出）已完成：`config set obsidian.vault <dir>` 配置库路径，`obsidian export` 将会话总结、已 accept 的经验和项目索引写成带 frontmatter + managed block 的 Markdown 笔记。更新采用非破坏式协议——保留用户手写区，托管块被手动改动时标记冲突并跳过，`--force` 才覆盖；`obsidian check` 只读扫描 vault 报告 drift/missing。
-- 经验生命周期：`experiences propose` 落库为候选（`experience_candidates`），`experiences candidates` 列出待审，`experiences accept/reject` 决定去留；accept 会把候选提升为正式 `experiences` 并建立 `session_experience_links`，再由 `obsidian export` 写出。
-- AI 助手集成：`skills init` 把一个中文 skill（`aiwiki-knowledge`）写入当前项目的 `.agents/skills/`，让 Claude Code / Codex / Cursor 读了即可自驱动「采集 → 总结 → 经验 → 导出」全流程，并内置了 YAML 输出规则避免格式错误。
+```bash
+llm-iwiki init
+llm-iwiki sync
+llm-iwiki projects list
+llm-iwiki projects inspect .
+```
+
+Configure an Obsidian vault and export notes:
 
 ```bash
-llm-iwiki sync                                          # 采集本地 AI 工具会话
-llm-iwiki projects list                                 # 按项目查看会话数
-llm-iwiki projects inspect .                            # 查看某项目下各工具的会话
-llm-iwiki summarize prepare changed --project .         # 生成会话总结任务
-llm-iwiki summarize apply --project . --file summaries.yaml
+llm-iwiki config set obsidian.vault ~/Obsidian/Vault
+llm-iwiki summarize prepare changed --project .
+llm-iwiki summarize apply --project . --file .llm-iwiki/exchange/summaries.yaml
 llm-iwiki experiences prepare --project . --from changed-summaries
-llm-iwiki experiences propose --project . --file experiences.yaml
-llm-iwiki experiences candidates --project .            # 查看经验候选
-llm-iwiki experiences accept <candidate-id>             # 采纳为正式经验
-llm-iwiki config set obsidian.vault ~/Obsidian/Vault    # 配置 Obsidian 库
-llm-iwiki obsidian export --project .                   # 导出为 Markdown 笔记
-llm-iwiki obsidian check                                # 检查笔记是否漂移
-llm-iwiki skills init                                   # 写入 AI 助手 skill 模板
+llm-iwiki experiences propose --project . --file .llm-iwiki/exchange/experiences.yaml
+llm-iwiki experiences candidates --project .
+llm-iwiki experiences accept <candidate-id>
+llm-iwiki obsidian export --project .
 ```
 
-### `skills init`
+The `prepare` commands generate task files for an AI assistant. Write the corresponding YAML files from those task files, then apply/propose them with the commands above.
 
-把中文 skill `aiwiki-knowledge` 写入当前项目的 `.agents/skills/`，让 Claude Code / Codex / Cursor 读了就能自驱动 `sync` → `summarize` → `experiences` → `obsidian export` 全流程。该 skill 内置了 YAML 输出规则（纯 YAML、不要代码围栏、不要占位符、`value` 四选一等），避免常见的格式错误。
+## Common Commands
+
+```bash
+llm-iwiki sync [--project <path>]
+llm-iwiki projects list
+llm-iwiki projects inspect <project>
+llm-iwiki projects dedupe
+llm-iwiki sessions list --project <project>
+llm-iwiki sessions read <session-id>
+llm-iwiki summarize prepare [changed|all] --project <project>
+llm-iwiki summarize apply --project <project> --file <summaries.yaml>
+llm-iwiki experiences prepare --project <project> [--since 30d]
+llm-iwiki experiences propose --project <project> --file <experiences.yaml>
+llm-iwiki experiences accept <candidate-id>
+llm-iwiki search <sessions|experiences> <query>
+llm-iwiki obsidian export [--project <project>|--all]
+llm-iwiki obsidian check
+```
+
+`<project>` can be a local path, a `proj_xxx` id, a display name, or a slug. If multiple projects match, use `projects list` to pick the exact project id.
+
+## Obsidian Output
+
+Exports are written under `LLM-iWiki/` in your configured vault:
+
+```text
+LLM-iWiki/
+├── README.md
+├── Projects/
+│   └── <project-slug>/
+│       ├── Project Summary.md
+│       ├── sessions/
+│       └── experiences/
+└── Topics/
+```
+
+Generated notes use frontmatter plus an `aiwiki:managed` block. You can write your own notes outside the managed block; re-exporting preserves those sections unless `--force` is used.
+
+## AI Assistant Skill
+
+Install the bundled `aiwiki-knowledge` skill into the current project:
 
 ```bash
-llm-iwiki skills                # 列出可用 target 与将写入的 skill（等同 skills list）
 llm-iwiki skills init [--target codex|claude-code|cursor] [--force] [--dry-run]
 ```
 
-- 裸 `skills` / `skills list`：只读列出可用 target 和将写入 `.agents/skills/` 的 skill，不落盘。
-- `--target`：在 skill 末尾附上对应助手（Codex / Claude Code / Cursor）的适配说明；省略则不附加。
-- `--force`：覆盖已存在的同名文件（默认跳过）。
-- `--dry-run`：只预演将写入/跳过的文件，不落盘。
+The skill teaches compatible assistants how to run the `sync -> summarize -> experiences -> export` workflow and how to produce valid YAML for `summarize apply` and `experiences propose`.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun test
+bun run build
+```
+
+This project uses Changesets for versioning, changelog generation, and npm publishing:
+
+```bash
+bun run changeset
+bun run version-packages
+bun run release
+```
+
+User-facing changes should include a `.changeset/*.md` file. GitHub Actions creates the release PR and publishes to npm after the release PR is merged.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## Roadmap
 
-## 待完成能力地图
+See [docs/roadmap.md](./docs/roadmap.md).
 
-以下为已在设计文档中规划、但尚未实现的进阶能力（按优先级粗排）：
+## License
 
-| 能力 | 命令 | 说明 | 状态 |
-| --- | --- | --- | --- |
-| 经验融合 | `experiences merge <candidate-id> <experience-id>` | 人工确认后把候选正文融合进已有经验，先生成 `merge-preview-*.md` 预览，确认后改写 managed block，合并 `source_sessions` / `evidence`，保留用户手写区 | 待开发 |
-| 项目目录迁移 | `obsidian move-project <project-id>` | `projects rename` 后按 `obsidian_notes` 映射与 frontmatter 中的 `aiwiki_project_id` 迁移 vault 目录，目标已存在时先做冲突检查 | 待开发 |
-| 结构化检索 | `search [sessions\|experiences] <query>` | SQLite FTS5 为主检索（projects / sessions / messages / summaries / experiences），可选 ripgrep 检索已导出 Markdown，`--index sqlite\|obsidian\|all` 切换 | 待开发 |
-| 打开笔记 | `obsidian open <note-id>` | 在 Obsidian 中直接打开对应笔记 | 待开发 |
-| 路径冲突批处理 | `obsidian export --overwrite-conflicts \| --skip-conflicts` | 目录迁移 / 导出时对路径冲突批量选择，跳过的标记 `conflict_status=path_conflict` 供 `obsidian check` 持续报告 | 待开发 |
-| 增量范围导出 | `obsidian export --changed \| --all` | 按变更范围而非单项目导出 | 待开发 |
-| 时间窗筛选 | `experiences prepare --since 30d` | 经验提炼任务按时间窗口限定来源摘要 | 待开发 |
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,146 @@
+# llm-iwiki
+
+[English](./README.md)
+
+[![npm version](https://img.shields.io/npm/v/@codehourra/llm-iwiki.svg)](https://www.npmjs.com/package/@codehourra/llm-iwiki)
+[![npm downloads](https://img.shields.io/npm/dm/@codehourra/llm-iwiki.svg)](https://www.npmjs.com/package/@codehourra/llm-iwiki)
+[![Node.js](https://img.shields.io/node/v/@codehourra/llm-iwiki.svg)](https://www.npmjs.com/package/@codehourra/llm-iwiki)
+[![Release](https://github.com/CodeHourra/llm-iwiki/actions/workflows/release.yml/badge.svg)](https://github.com/CodeHourra/llm-iwiki/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Changelog](https://img.shields.io/badge/changelog-CHANGELOG.md-blue)](./CHANGELOG.md)
+
+把本地 AI 编程会话沉淀为可检索的 Obsidian 知识库。
+
+`llm-iwiki` 会采集 Claude Code、Cursor、Codex、Gemini 和 CodeBuddy 的本地会话记录，按项目归一化到 SQLite，生成适合 AI 助手处理的总结任务，保存经过确认的项目经验，并导出为可导航的 Obsidian Markdown 笔记。
+
+## 功能特性
+
+- 采集多个 AI 编程工具的本地会话记录。
+- 按项目、仓库、路径或 slug 解析和归类会话。
+- 为 AI 助手生成会话总结和经验提取任务文件。
+- 在发布到知识库前审核并采纳可复用的工程经验。
+- 导出项目摘要、会话笔记和项目经验到 Obsidian。
+- 更新托管内容块时保留用户手写区域。
+- 通过 CLI 检索会话摘要和已采纳经验。
+
+## 环境要求
+
+- 运行时需要 Node.js 20 或更高版本。
+- 本地开发、测试和构建需要 Bun。
+
+SQLite 由 `better-sqlite3` 提供；npm 安装时会自动下载可用的预编译二进制。
+
+## 安装
+
+```bash
+npm install -g @codehourra/llm-iwiki
+```
+
+也可以不全局安装，直接使用 `npx`：
+
+```bash
+npx @codehourra/llm-iwiki --help
+```
+
+## 快速开始
+
+```bash
+llm-iwiki init
+llm-iwiki sync
+llm-iwiki projects list
+llm-iwiki projects inspect .
+```
+
+配置 Obsidian 库并导出笔记：
+
+```bash
+llm-iwiki config set obsidian.vault ~/Obsidian/Vault
+llm-iwiki summarize prepare changed --project .
+llm-iwiki summarize apply --project . --file .llm-iwiki/exchange/summaries.yaml
+llm-iwiki experiences prepare --project . --from changed-summaries
+llm-iwiki experiences propose --project . --file .llm-iwiki/exchange/experiences.yaml
+llm-iwiki experiences candidates --project .
+llm-iwiki experiences accept <candidate-id>
+llm-iwiki obsidian export --project .
+```
+
+`prepare` 命令会生成供 AI 助手阅读的任务文件。根据任务文件编写对应 YAML 后，再用上面的 `apply` / `propose` 命令落库。
+
+## 常用命令
+
+```bash
+llm-iwiki sync [--project <path>]
+llm-iwiki projects list
+llm-iwiki projects inspect <project>
+llm-iwiki projects dedupe
+llm-iwiki sessions list --project <project>
+llm-iwiki sessions read <session-id>
+llm-iwiki summarize prepare [changed|all] --project <project>
+llm-iwiki summarize apply --project <project> --file <summaries.yaml>
+llm-iwiki experiences prepare --project <project> [--since 30d]
+llm-iwiki experiences propose --project <project> --file <experiences.yaml>
+llm-iwiki experiences accept <candidate-id>
+llm-iwiki search <sessions|experiences> <query>
+llm-iwiki obsidian export [--project <project>|--all]
+llm-iwiki obsidian check
+```
+
+`<project>` 可以是本地路径、`proj_xxx` 项目 id、展示名或 slug。如果匹配到多个项目，请先用 `projects list` 找到准确的项目 id。
+
+## Obsidian 输出结构
+
+导出内容会写入已配置 vault 下的 `LLM-iWiki/` 目录：
+
+```text
+LLM-iWiki/
+├── README.md
+├── Projects/
+│   └── <project-slug>/
+│       ├── Project Summary.md
+│       ├── sessions/
+│       └── experiences/
+└── Topics/
+```
+
+生成的笔记包含 frontmatter 和 `aiwiki:managed` 托管内容块。你可以在托管块之外自由补充内容；重新导出时会保留这些手写内容，除非显式使用 `--force`。
+
+## AI 助手 Skill
+
+将内置的 `aiwiki-knowledge` skill 安装到当前项目：
+
+```bash
+llm-iwiki skills init [--target codex|claude-code|cursor] [--force] [--dry-run]
+```
+
+这个 skill 会教兼容的 AI 助手如何执行 `sync -> summarize -> experiences -> export` 流程，以及如何为 `summarize apply` 和 `experiences propose` 生成合法 YAML。
+
+## 开发
+
+```bash
+bun install
+bun run typecheck
+bun test
+bun run build
+```
+
+项目使用 Changesets 管理版本号、变更记录和 npm 发布：
+
+```bash
+bun run changeset
+bun run version-packages
+bun run release
+```
+
+面向用户的变更应包含一个 `.changeset/*.md` 文件。GitHub Actions 会创建发布 PR，并在发布 PR 合并后发布到 npm。
+
+## 变更记录
+
+见 [CHANGELOG.md](./CHANGELOG.md)。
+
+## 路线图
+
+见 [docs/roadmap.zh-CN.md](./docs/roadmap.zh-CN.md)。
+
+## 许可证
+
+[MIT](./LICENSE)