dsh-grove 0.2.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/README.en.md +34 -74
  2. package/README.md +35 -77
  3. package/client.js +760 -143
  4. package/package.json +3 -2
  5. package/src/adapters/models/http.js +24 -0
  6. package/src/adapters/parsers/documents.js +31 -0
  7. package/src/adapters/storage/obsidian/backup.js +104 -0
  8. package/src/cli.js +11 -3
  9. package/src/modules/evidence.js +38 -0
  10. package/src/modules/inspirations.js +18 -0
  11. package/src/modules/knowledge.js +29 -0
  12. package/src/modules/model-research.js +27 -0
  13. package/src/modules/reports.js +57 -0
  14. package/src/modules/research.js +17 -0
  15. package/src/modules/version-reference.js +4 -0
  16. package/src/modules/works.js +27 -0
  17. package/src/plugin.js +10 -2
  18. package/src/proposals.js +1 -1
  19. package/src/server.js +234 -2
  20. package/src/vault.js +16 -1
package/README.en.md CHANGED
@@ -2,102 +2,62 @@
2
2
 
3
3
  ![Grove. Build knowledge you can revisit and revise.](brand/exports/readme-header-1600x480.en.png)
4
4
 
5
- [简体中文](README.md) · [English](README.en.md)
5
+ [简体中文](README.md) · [English](README.en.md) · [MIT license](LICENSE)
6
6
 
7
- [![MIT license](https://img.shields.io/badge/license-MIT-2F7D5B?style=flat-square)](LICENSE)
8
- [![DeepSeek Harness 0.2.2-rc.1 up to 0.3.0](https://img.shields.io/badge/dsh-%3E%3D0.2.2--rc.1_%3C0.3.0-1B3A2E?style=flat-square)](package.json)
9
- [![Node.js 22 or later](https://img.shields.io/badge/Node.js-22%2B-2F7D5B?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
7
+ ## Why Grove exists
10
8
 
11
- ## Personal knowledge and growth
9
+ Grove started with a question. How can an idea, a conversation, or a round of research become knowledge you can find, verify, and revise later? Grove connects DeepSeek Harness to your own Obsidian vault so that work stays with you as Markdown.
12
10
 
13
- **PKGS (Personal Knowledge & Growth System) is a method for long-term personal growth.** It connects exploration, learning, evidence-based research, creation, and reflection. Something you understood years ago may help explain a problem today. Evidence you find tomorrow may change a judgment you make today. Over time, you build knowledge you can draw on again and become better at understanding, judging, researching, and communicating.
11
+ The Personal Knowledge & Growth System (PKGS) connects exploration, learning, research, creation, and reflection. You can jot down a sentence or revise a judgment after trying it in practice, then carry that understanding into your next study. AI can compare explanations, ask questions, and draft. You decide what to believe, keep, and share. [PKGS guide](docs/PKGS.en.md)
14
12
 
15
- You can practice the method with paper, Markdown, or tools you already use. The [PKGS guide](docs/PKGS.en.md) explains the design and shows how to develop questions, connect ideas, conduct research, track changes in your views, and share the work with AI.
13
+ ## Core features
16
14
 
17
- - **Exploration** starts with an observation, uncertainty, or association. You can stop anytime or leave an open question to return to later. You decide when to research it and whether to make something from it.
18
- - **Knowledge growth** starts by explaining an idea in your own words. Connect concepts, examples, and questions, then test your understanding through use and review.
19
- - **Research and creation** start with a question worth investigating. Preserve sources, counterexamples, and versions of your judgment. When useful, turn what you learned into an article, report, or proposal. Reflection can give you a starting point for the next exploration.
15
+ The features below describe this repository. Installations from npm use the version published in the registry. [npm package](https://www.npmjs.com/package/dsh-grove)
20
16
 
21
- AI can ask questions, compare explanations, surface counterexamples, and help you express an idea. You decide what to believe, keep, and share.
17
+ - **Capture ideas.** Jot down a thought, find it by keyword, and reopen an earlier version.
18
+ - **Research with evidence.** Start an independent study or configure a model to analyze selected excerpts. Import Markdown or PDFs with a text layer, save passages with paragraph or page locations, and confirm a report after review.
19
+ - **Build knowledge and create works.** Turn findings into concepts or methods, and use your knowledge to draft a work. Record why your understanding changed while keeping earlier references readable.
20
+ - **Keep your data locally.** Notes and versions live in the vault’s `Grove/` folder. The CLI can verify a backup and restore it to a separate directory.
22
21
 
23
- ## How Grove puts the method into practice
22
+ ## Install and use
24
23
 
25
- Grove connects DeepSeek Harness and Obsidian. The current version connects the Grove panel in the left sidebar, open-ended conversation, user-confirmed saves, and basic evidence tracking. After installing, Grove appears in the sidebar: connect a vault and capture a first idea, then return to the conversation. Choose what to keep from a conversation, save it as Markdown in your own vault, and use versions and wikilinks to revisit relationships among questions, evidence, and claims. You can practice the guide’s learning, reflection, and full research methods by hand.
24
+ Have an Obsidian vault ready. Check [`engines` in package.json](package.json) for the supported Node.js and DeepSeek Harness versions.
26
25
 
27
- ## Install v0.2.0
28
-
29
- You need Node.js 22 or later, an existing Obsidian vault, and DeepSeek Harness `>=0.2.2-rc.1 <0.3.0`. The `engines.dsh` range determines whether the host loads the bundle.
30
-
31
- ### Install in an existing Harness
32
-
33
- | Entry point | Steps |
34
- | --- | --- |
35
- | Desktop | Open **Plugins → Add plugin** and select this repository directory. The host installs a `link:` dependency. Restart the host after editing the source. |
36
- | In a session | Ask the agent to call `plugin_manager` with `install_bundle` and pass the directory’s absolute path as `target`. |
37
- | npm | `dsh plugin --profile <profile> add dsh-grove` (published to npm since 0.2.0). |
38
- | CLI | Run `dsh plugin --profile <profile> add <directory-or-tgz>`. The Desktop app manages its own profile. Packages installed into `profiles/web` do not appear there. |
39
-
40
- After installing, **Grove** appears in the left sidebar: open it, choose a vault, and capture a first idea. Check that Grove also appears on the **Plugins** page, then ask the model to call `grove_role` in a new session to confirm the tool is registered.
41
-
42
- ### Try a separate profile
43
-
44
- ```sh
45
- export GROVE_VAULT="/absolute/path/to/Obsidian vault"
46
- npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove add "$PWD"
47
- npx --yes @deepseek-ai/dsh@0.2.2-rc.3 --profile grove
48
- ```
49
-
50
- Initialize a separate profile once. If the `grove` profile already exists, install or launch directly. In your trial profile, keep host shell access, file editing, general automation, and other extensions from accessing the vault or running confirmation commands on your behalf. Grove’s model tools provide role guidance, drafts, and allowlisted reads. Harness sessions also follow the host’s routing, permissions, and history settings.
51
-
52
- ### Install the command-line tool
53
-
54
- A global installation puts the package’s `grove` executable on PATH. Installing the plugin in a profile registers it with the host.
26
+ - **Install from npm.** Run `dsh plugin --profile <profile> add dsh-grove`.
27
+ - **Try the source in Desktop.** Open **Plugins → Add plugin** and select this repository directory. Restart the host after editing the source. Desktop manages its own profile.
28
+ - **Try the source in a separate profile.** From the repository root, run the following commands.
55
29
 
56
30
  ```sh
57
- npm pack --pack-destination /tmp
58
- npm install --global /tmp/dsh-grove-0.2.0.tgz
31
+ dsh plugin --profile grove-trial add "$PWD"
32
+ dsh --profile grove-trial
59
33
  ```
60
34
 
61
- ## Everyday use
62
-
63
- 1. Open **Grove** in the left sidebar, choose your Obsidian vault, and capture a first idea. You can also keep using the terminal: `grove capture --body 'Why might coordination costs increase as an organization grows?'`. Open the `Grove` folder in Obsidian to see the Markdown note.
64
- 2. Explore in Harness. Use `grove_role` for a thinking partner, knowledge assistant, research assistant, critical reviewer, or creation assistant. Ask `grove_propose` to draft a note when you want to keep something, and supply the conversation reference you want to save. You can also end the exploration there.
65
- 3. Run `grove preview DRAFT_ID` in your terminal. Use `grove accept DRAFT_ID` and type `SAVE`, or run `grove discard DRAFT_ID`. Pass `--file` when accepting to supply your edited body.
66
- 4. Use `grove list` and `grove show ASSET_ID --version 1` to revisit your notes. To share selected notes with the model, set `GROVE_READABLE_IDS` to a comma-separated list of asset IDs before starting the host. Restart the host after revoking that access. Content already shared in a session follows the host’s history settings.
35
+ Open **Grove** (or **知林** in Chinese) in the sidebar, choose your vault, and save an idea. Open **Research** to save a question and observations, then add sources, capture evidence, or confirm a report as needed. For AI research, enter a Chat Completions-compatible HTTPS endpoint and model name in the research panel, and set `GROVE_MODEL_KEY` in the host environment.
67
36
 
68
- ## Basic research
37
+ Install the CLI separately with `npm install --global .` from the repository root, or run `npm install --global dsh-grove` for the published CLI.
69
38
 
70
39
  ```sh
71
- grove add question --body 'How does team size affect decision speed?'
72
- grove add research --question QUESTION_ID --body 'Compare decision authority and coordination costs'
73
- grove add evidence --body 'Add a checkable excerpt' --source 'https://example.org/report' --locator 'Page 12, paragraph 2'
74
- grove add claim --body 'My current judgment'
75
- grove update CLAIM_ID --version 1 --link EVIDENCE_ID --relation supports
76
- grove update RESEARCH_ID --version 1 --link CLAIM_ID --relation related
77
- grove update RESEARCH_ID --version 2 --stage analysis
78
- grove update RESEARCH_ID --version 3 --stage review --status closed
40
+ export GROVE_VAULT="/absolute/path/to/Obsidian vault"
41
+ grove capture --body 'Why do the two sides of this street feel so different?'
42
+ grove list
43
+ grove show ASSET_ID --version 1
79
44
  ```
80
45
 
81
- Use the IDs returned by the earlier commands. You can revisit stages and pause, reopen, or archive questions and projects. Evidence can support, refute, or qualify a claim. Links target specific versions. When you rewrite a claim, its earlier evidence links stay on the earlier version. You can explicitly adopt evidence again for the new version. A research project can close with or without a deliverable.
82
-
83
- ## Data and removal
46
+ In a Harness session, use `grove_role` for collaboration guidance and `grove_propose` for drafts. Back in your terminal, run `grove preview DRAFT_ID`, then `grove accept DRAFT_ID` to confirm or `grove discard DRAFT_ID` to discard. To share selected assets with the model, configure the read allowlist. [Tools and permissions](docs/DETAIL.en.md)
84
47
 
85
- Version files in `Grove/` use YAML properties, Markdown bodies, and Obsidian wikilinks. Grove reads within its own folder. Copy the whole folder, including hidden drafts, to back it up or move it. You can read and edit bodies in Obsidian while preserving file names and Grove metadata. Use `grove update` to retain the earlier version. The current version records source identifiers and locations you supply. See the [plugin details](docs/DETAIL.en.md) for current limits.
86
-
87
- To remove the host plugin, run `npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove remove dsh-grove`. Your vault data stays in place. Remove the command separately with `npm uninstall --global dsh-grove`.
88
-
89
- ## Brand assets
90
-
91
- See the [brand assets](brand/README.en.md) and the visual identity guide ([English](brand/VI.en.md) · [简体中文](brand/VI.md)). Tests check that the package’s `icon.svg` matches `brand/mark.svg` byte for byte.
48
+ Before upgrading, pause writes and run `grove backup /absolute/path/to/snapshot`. To restore, run `grove restore /absolute/path/to/snapshot --destination /absolute/path/to/new-vault`, check the restored files, and switch the panel to that directory. To remove the plugin, run `dsh plugin --profile <profile> remove dsh-grove`. Your vault data stays in place.
92
49
 
93
50
  ## Contributing
94
51
 
95
- Read the [development contract](AGENTS.en.md) ([简体中文](AGENTS.md)). The Claude Code, Cursor, and Copilot instructions point to the same contract. See the [development guide](docs/development/README.md) for issue structure, acceptance, and review rules, and the [journal](docs/journal/) for handoffs. Before making changes, run the tests and `bash scripts/check-compat.sh`.
96
-
97
- ## Verify from source
52
+ 1. Check open issues. For a bug, include reproduction steps and the expected and actual behavior. For a feature, describe what the user needs and how to verify it. [Issues](https://github.com/kmeng/dsh-grove/issues)
53
+ 2. Read the development contract and open a branch for a change reviewers can verify in one PR. Use a temporary vault and include actual test results and any gaps. [Development contract](AGENTS.en.md) · [Development guide](docs/development/README.md)
54
+ 3. Run the checks below. Documentation and brand-only changes need the first two. Host checks use an installed dsh and a temporary profile.
98
55
 
99
56
  ```sh
100
- npm ci
101
- npm test
102
- npm pack
57
+ npm ci && npm test
58
+ npm pack --dry-run --json
59
+ bash scripts/check-compat.sh
60
+ bash scripts/verify-install.sh
103
61
  ```
62
+
63
+ See the [journal](docs/journal/) for handoffs and release history and the [brand guide](brand/README.en.md) for logos and visual identity.
package/README.md CHANGED
@@ -2,104 +2,62 @@
2
2
 
3
3
  ![Grove 知林，积累可回看、可修正的知识](brand/exports/readme-header-1600x480.zh.png)
4
4
 
5
- [简体中文](README.md) · [English](README.en.md)
5
+ [简体中文](README.md) · [English](README.en.md) · [MIT 许可](LICENSE)
6
6
 
7
- [![MIT 许可](https://img.shields.io/badge/license-MIT-2F7D5B?style=flat-square)](LICENSE)
8
- [![DeepSeek Harness 0.2.2-rc.1 至 0.3.0 之前](https://img.shields.io/badge/dsh-%3E%3D0.2.2--rc.1_%3C0.3.0-1B3A2E?style=flat-square)](package.json)
9
- [![Node.js 22 或更高](https://img.shields.io/badge/Node.js-22%2B-2F7D5B?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
7
+ ## 缘起
10
8
 
11
- ## 个人知识与认知成长
9
+ 知林源于一个问题：怎样让一次对话、一条灵感或一轮研究，成为以后还能找回、核对和修正的知识？Grove 把 DeepSeek Harness 与你自己的 Obsidian vault 连起来，让这些内容以 Markdown 留在手边。
12
10
 
13
- **PKGS（Personal Knowledge & Growth System）是一套面向个人长期成长的方法。** 它把思想探索、知识学习、证据研究、创造和反思接起来。过去读懂的东西可以解释今天遇到的问题，今天形成的判断也可以因明天发现的证据而改变。长期积累的是能重新调用的知识，以及理解、判断、研究和表达的能力。
11
+ 背后的 PKGS（Personal Knowledge & Growth System）把思想探索、学习、研究、创作和反思连在一起。你可以只记一句话，也可以在实践后修正自己的判断，把更新后的理解带进下一轮研究。AI 可以帮你比较解释、追问和起草，你决定相信什么、留下什么以及分享什么。 [PKGS 方法指南](docs/PKGS.zh.md)
14
12
 
15
- 这套方法可以用纸笔、Markdown 或自己熟悉的工具实践。[PKGS 方法指南](docs/PKGS.zh.md)从设计依据讲到日常操作，包括如何孵化问题、建立知识关联、开展研究、记录观点的变化，以及怎样与 AI 分工。
13
+ ## 核心功能
16
14
 
17
- - **思想探索**从一个观察、困惑或联想开始。你可以随时停下，也可以留一个开放问题以后接着想。研究和产出都由你选择。
18
- - **知识成长**从用自己的话解释开始。把概念、例子和疑问连起来，在应用和回顾中检验理解。
19
- - **研究与创造**从值得核查的问题开始。保留来源、反例和判断的不同版本，需要时把形成的认识写成文章、报告或方案。复盘所得可以成为下一轮探索的起点。
15
+ 以下功能以本仓库源码为准。通过 npm 安装时，以注册表已发布的版本为准。 [npm 包](https://www.npmjs.com/package/dsh-grove)
20
16
 
21
- AI 可以追问、比较解释、查找反例和协助表达。你决定相信什么、留下什么以及和谁分享。
17
+ - **叮一下**。记下一句灵感，之后按关键词找回，也能打开历史版本。
18
+ - **研究与证据**。直接发起独立研究，或配置模型分析选定的摘录。导入 Markdown 和有文本层的 PDF，给摘录留下段落或页码，核对后保存报告。
19
+ - **知识与作品**。从报告提炼概念或方法，用已有知识起草作品。修订知识时记录原因，旧作品仍可回查当时使用的版本。
20
+ - **本地数据**。笔记和历史版本保存在 vault 的 `Grove/` 目录。CLI 可创建校验过的备份并恢复到独立目录。
22
21
 
23
- ## Grove 如何实践这套方法
22
+ ## 安装与使用
24
23
 
25
- Grove 是连接 DeepSeek Harness 和 Obsidian 的插件。当前版本把左侧 Grove 面板、自由对话、自主保存和基础证据研究接在一起。安装后左侧菜单出现 Grove：连接 vault、写下第一条灵感；回到会话里让 AI 陪你追问。你可以从会话挑出值得保留的内容，把它保存成自己 vault 里的 Markdown，并用版本和双链回看问题、证据与判断的关联。指南里的学习、反思和完整研究方法可以手工实践。
24
+ 准备一个 Obsidian vault。Node.js 与 DeepSeek Harness 的兼容要求见 [package.json 的 `engines`](package.json)。
26
25
 
27
- ## 安装 v0.2.0
28
-
29
- 需要 Node.js 22 或更高版本、一个已有的 Obsidian vault，以及 DeepSeek Harness `>=0.2.2-rc.1 <0.3.0`。兼容范围由 `engines.dsh` 声明：它必须是范围而不是某一个精确版本，否则 dsh 会把整个 bundle 判为不兼容并跳过加载。
30
-
31
- ### 装进现有的 Harness
32
-
33
- | 入口 | 做法 |
34
- | --- | --- |
35
- | Desktop | **Plugins → Add plugin**，选择本仓库目录；按目录安装会装成 `link:`，改完代码重启宿主即生效 |
36
- | 会话里 | 让 agent 调用 `plugin_manager` 的 `install_bundle`，`target` 传目录绝对路径 |
37
- | npm | `dsh plugin --profile <profile> add dsh-grove`（0.2.0 起已发布到 npm） |
38
- | CLI | `dsh plugin --profile <profile> add <目录或 tgz>`。Desktop 的 profile 由 App 管理，命令行装进 `profiles/web` 不会出现在 Desktop |
39
-
40
- 装完左侧菜单出现 **Grove**：点开选择 vault，写下第一条灵感。再到 **Plugins** 页确认 Grove 这一条出现，并在新会话里让模型调用 `grove_role`——工具真的注册上才算装好。
41
-
42
- ### 独立 profile 试用（不碰日常配置）
26
+ - **从 npm 安装**。运行 `dsh plugin --profile <profile> add dsh-grove`。
27
+ - **在 Desktop 试用源码**。在 **Plugins → Add plugin** 选择本仓库目录。修改源码后重启宿主。Desktop 使用自己管理的 profile。
28
+ - **用独立 profile 试用源码**。在仓库根目录执行以下命令。
43
29
 
44
30
  ```sh
45
- export GROVE_VAULT="/absolute/path/to/Obsidian vault"
46
- npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove add "$PWD"
47
- npx --yes @deepseek-ai/dsh@0.2.2-rc.3 --profile grove
31
+ dsh plugin --profile grove-trial add "$PWD"
32
+ dsh --profile grove-trial
48
33
  ```
49
34
 
50
- 独立配置只初始化一次；已有 `grove` 配置时直接安装或启动。用独立配置试用，确保宿主的 Bash、文件编辑、通用自动化和其他扩展无法访问 vault 或代你运行本地确认命令。Grove 自身的模型工具只有角色提示、草稿和白名单查询。普通 Harness 会话仍遵循宿主的模型路由、权限和历史保留设置。
35
+ 装好后，从左侧打开中文界面的 **知林** 或英文界面的 **Grove**，选择 vault，写下一句并点「💡叮～」。想研究一个问题时，打开「研究」，保存问题和观察，再按需上传资料、保存摘录与确认报告。使用「AI 深挖」前，在研究面板填写兼容 Chat Completions 的 HTTPS 接口和模型名称，并在宿主环境设置 `GROVE_MODEL_KEY`。
51
36
 
52
- ### 命令行工具
53
-
54
- `grove` 命令来自包里的 `bin`，要全局安装才有；把插件装进某个 profile **不会**把它加进 PATH：
37
+ 也可以单独安装终端命令。在仓库根目录执行 `npm install --global .` 可安装源码中的 CLI。执行 `npm install --global dsh-grove` 可安装 npm 已发布的 CLI。
55
38
 
56
39
  ```sh
57
- npm pack --pack-destination /tmp
58
- npm install --global /tmp/dsh-grove-0.2.0.tgz
59
- ```
60
-
61
- ## 日常使用
62
-
63
- 1. 点开左侧菜单的 **Grove**，选择你的 Obsidian vault，写下第一条灵感。也可以继续用终端：`grove capture --body '为什么组织扩大后协调成本会上升？'`。在 Obsidian 中打开 vault 的 `Grove` 文件夹可看到 Markdown 笔记。
64
- 2. 在 Harness 中自由对话。可要求使用 `grove_role` 作为思想伙伴、知识助手、研究助手、批判性审查者或创造助手。想保留一段讨论时，请求 `grove_propose` 起草，并提供你愿意保存的会话引用。探索可以直接结束。
65
- 3. 在自己的终端执行 `grove preview 草稿ID`。用 `grove accept 草稿ID` 查看并输入 `SAVE`，或执行 `grove discard 草稿ID`。确认时也可用 `--file` 提供你编辑过的正文。
66
- 4. 用 `grove list` 查询资产，用 `grove show 资产ID --version 1` 回看具体版本。默认 Grove 不向模型提供资产正文。若希望分享指定笔记，启动宿主前将 `GROVE_READABLE_IDS` 设为逗号分隔的资产 ID。取消分享后重新启动宿主。已进入宿主会话的内容仍受宿主历史设置约束。
67
-
68
- ## 基础研究
69
-
70
- ```sh
71
- grove add question --body '团队规模如何影响决策效率？'
72
- grove add research --question QUESTION_ID --body '比较决策权限和协调成本'
73
- grove add evidence --body '粘贴可核对的摘录' --source 'https://example.org/report' --locator '第12页第2段'
74
- grove add claim --body '我目前的判断'
75
- grove update CLAIM_ID --version 1 --link EVIDENCE_ID --relation supports
76
- grove update RESEARCH_ID --version 1 --link CLAIM_ID --relation related
77
- grove update RESEARCH_ID --version 2 --stage analysis
78
- grove update RESEARCH_ID --version 3 --stage review --status closed
40
+ export GROVE_VAULT="/absolute/path/to/Obsidian vault"
41
+ grove capture --body '同一条街，为什么两边走起来差这么多？'
42
+ grove list
43
+ grove show ASSET_ID --version 1
79
44
  ```
80
45
 
81
- 把示例 ID 替换成上一步返回的 ID。阶段可回退，问题和项目可暂停、重开或归档。证据关系可表达支持、反驳和限定，双链指向具体版本。重写观点正文时，旧证据关系留在原版本，用户可以为新版本重新采用证据。结束研究时，成果可选。
82
-
83
- ## 数据和卸载
84
-
85
- `Grove/` 内的版本文件使用 YAML 属性、Markdown 正文和 Obsidian 双链。Grove 不读 vault 中其他笔记。复制整个 `Grove/` 文件夹即可备份或迁移，点号开头的草稿文件也会随整目录迁移。可在 Obsidian 阅读及编辑正文，保留文件名和 Grove 元数据。要保留更改前的版本，使用 `grove update`。本版证据使用用户填写的来源标识与定位。当前能力的边界见[插件详情](docs/DETAIL.zh.md)。
46
+ 在 Harness 会话中，可用 `grove_role` 选协作角色，用 `grove_propose` 起草。回到终端用 `grove preview DRAFT_ID` 查看，再用 `grove accept DRAFT_ID` 确认或用 `grove discard DRAFT_ID` 丢弃。向模型开放指定资产时，按插件详情配置读取白名单。 [工具与权限说明](docs/DETAIL.zh.md)
86
47
 
87
- 用 `npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove remove dsh-grove` 卸载宿主插件。数据留在 vault，终端命令可通过 `npm uninstall --global dsh-grove` 单独卸载。
48
+ 升级前暂停对库的写入，用 `grove backup /absolute/path/to/snapshot` 校验备份。需要恢复时运行 `grove restore /absolute/path/to/snapshot --destination /absolute/path/to/new-vault`，检查后在面板切换到恢复目录。卸载可用 `dsh plugin --profile <profile> remove dsh-grove`，vault 数据保留。
88
49
 
89
- ## 品牌资产
50
+ ## 贡献代码
90
51
 
91
- 标志、锁定组合、色板、字体与导出图都在 [`brand/`](brand/README.md)，规范见 [`brand/VI.md`](brand/VI.md)（中文）与 [`brand/VI.en.md`](brand/VI.en.md)（English）。根目录的 `icon.svg` 与 `brand/mark.svg` 保持字节一致，由测试保证。
92
-
93
- ## 参与开发
94
-
95
- 规则只有一份：[`AGENTS.md`](AGENTS.md)（[English](AGENTS.en.md)）。Claude Code、Cursor、GitHub Copilot 分别读 `CLAUDE.md`、`.cursor/rules/project.mdc`、`.github/copilot-instructions.md`，三者都只指向 `AGENTS.md`。
96
-
97
- 理念、任务分层、DoD 与评审清单在 [`docs/development/`](docs/development/README.md)；会话交接在 [`docs/journal/`](docs/journal/)。改动前先跑 `npm test` 与 `bash scripts/check-compat.sh`。
98
-
99
- ## 从源代码验证
52
+ 1. 先看开放 issue。修 bug 时写清复现步骤、预期结果和实际结果。提功能时说明用户场景和可验证的验收条件。 [Issues](https://github.com/kmeng/dsh-grove/issues)
53
+ 2. 阅读开发契约，从分支提交一个可独立验收的 PR。用临时 vault 验证，附上实际测试结果和未覆盖的情况。 [开发契约](AGENTS.md) · [开发指南](docs/development/README.md)
54
+ 3. 本地运行下列检查。只改文档或品牌素材时跑前两项。宿主验证用已安装的 dsh 和临时 profile。
100
55
 
101
56
  ```sh
102
- npm ci
103
- npm test
104
- npm pack
57
+ npm ci && npm test
58
+ npm pack --dry-run --json
59
+ bash scripts/check-compat.sh
60
+ bash scripts/verify-install.sh
105
61
  ```
62
+
63
+ 项目交接与发布记录见 [journal](docs/journal/)。标志和视觉规范见 [品牌资产](brand/README.md)。