dsh-grove 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wali@2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,102 @@
+# Grove
+
+![Grove. Build knowledge you can revisit and revise.](brand/exports/readme-header-1600x480.en.png)
+
+[简体中文](README.md) · [English](README.en.md)
+
+[![MIT license](https://img.shields.io/badge/license-MIT-2F7D5B?style=flat-square)](LICENSE)
+[![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)
+[![Node.js 22 or later](https://img.shields.io/badge/Node.js-22%2B-2F7D5B?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
+
+## Personal knowledge and growth
+
+**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.
+
+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.
+
+- **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.
+- **Knowledge growth** starts by explaining an idea in your own words. Connect concepts, examples, and questions, then test your understanding through use and review.
+- **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.
+
+AI can ask questions, compare explanations, surface counterexamples, and help you express an idea. You decide what to believe, keep, and share.
+
+## How Grove puts the method into practice
+
+Grove connects DeepSeek Harness and Obsidian. The current version connects open-ended conversation, user-confirmed saves, and basic evidence tracking. 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.
+
+## Install v0.1.1
+
+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.
+
+### Install in an existing Harness
+
+| Entry point | Steps |
+| --- | --- |
+| Desktop | Open **Plugins → Add plugin** and select this repository directory. The host installs a `link:` dependency. Restart the host after editing the source. |
+| In a session | Ask the agent to call `plugin_manager` with `install_bundle` and pass the directory’s absolute path as `target`. |
+| 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. |
+
+Check that Grove appears on the **Plugins** page, then ask the model to call `grove_role` in a new session to confirm the tool is registered.
+
+### Try a separate profile
+
+```sh
+export GROVE_VAULT="/absolute/path/to/Obsidian vault"
+npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove add "$PWD"
+npx --yes @deepseek-ai/dsh@0.2.2-rc.3 --profile grove
+```
+
+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.
+
+### Install the command-line tool
+
+A global installation puts the package’s `grove` executable on PATH. Installing the plugin in a profile registers it with the host.
+
+```sh
+npm pack --pack-destination /tmp
+npm install --global /tmp/dsh-grove-0.1.1.tgz
+```
+
+## Everyday use
+
+1. Run `grove capture --body 'Why might coordination costs increase as an organization grows?'` and open the `Grove` folder in Obsidian to see the Markdown note.
+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.
+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.
+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.
+
+## Basic research
+
+```sh
+grove add question --body 'How does team size affect decision speed?'
+grove add research --question QUESTION_ID --body 'Compare decision authority and coordination costs'
+grove add evidence --body 'Add a checkable excerpt' --source 'https://example.org/report' --locator 'Page 12, paragraph 2'
+grove add claim --body 'My current judgment'
+grove update CLAIM_ID --version 1 --link EVIDENCE_ID --relation supports
+grove update RESEARCH_ID --version 1 --link CLAIM_ID --relation related
+grove update RESEARCH_ID --version 2 --stage analysis
+grove update RESEARCH_ID --version 3 --stage review --status closed
+```
+
+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.
+
+## Data and removal
+
+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.
+
+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`.
+
+## Brand assets
+
+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.
+
+## Contributing
+
+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`.
+
+## Verify from source
+
+```sh
+npm ci
+npm test
+npm pack
+```

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# Grove（知林）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![Grove 知林，积累可回看、可修正的知识](brand/exports/readme-header-1600x480.zh.png)
+
+[简体中文](README.md) · [English](README.en.md)
+
+[![MIT 许可](https://img.shields.io/badge/license-MIT-2F7D5B?style=flat-square)](LICENSE)
+[![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)
+[![Node.js 22 或更高](https://img.shields.io/badge/Node.js-22%2B-2F7D5B?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
+
+## 个人知识与认知成长
+
+**PKGS（Personal Knowledge & Growth System）是一套面向个人长期成长的方法。** 它把思想探索、知识学习、证据研究、创造和反思接起来。过去读懂的东西可以解释今天遇到的问题，今天形成的判断也可以因明天发现的证据而改变。长期积累的是能重新调用的知识，以及理解、判断、研究和表达的能力。
+
+这套方法可以用纸笔、Markdown 或自己熟悉的工具实践。[PKGS 方法指南](docs/PKGS.zh.md)从设计依据讲到日常操作，包括如何孵化问题、建立知识关联、开展研究、记录观点的变化，以及怎样与 AI 分工。
+
+- **思想探索**从一个观察、困惑或联想开始。你可以随时停下，也可以留一个开放问题以后接着想。研究和产出都由你选择。
+- **知识成长**从用自己的话解释开始。把概念、例子和疑问连起来，在应用和回顾中检验理解。
+- **研究与创造**从值得核查的问题开始。保留来源、反例和判断的不同版本，需要时把形成的认识写成文章、报告或方案。复盘所得可以成为下一轮探索的起点。
+
+AI 可以追问、比较解释、查找反例和协助表达。你决定相信什么、留下什么以及和谁分享。
+
+## Grove 如何实践这套方法
+
+Grove 是连接 DeepSeek Harness 和 Obsidian 的插件。当前版本把自由对话、自主保存和基础证据研究接在一起。你可以从会话挑出值得保留的内容，把它保存成自己 vault 里的 Markdown，并用版本和双链回看问题、证据与判断的关联。指南里的学习、反思和完整研究方法可以手工实践。
+
+## 安装 v0.1.2
+
+需要 Node.js 22 或更高版本、一个已有的 Obsidian vault，以及 DeepSeek Harness `>=0.2.2-rc.1 <0.3.0`。兼容范围由 `engines.dsh` 声明：它必须是范围而不是某一个精确版本，否则 dsh 会把整个 bundle 判为不兼容并跳过加载。
+
+### 装进现有的 Harness
+
+| 入口 | 做法 |
+| --- | --- |
+| Desktop | **Plugins → Add plugin**，选择本仓库目录；按目录安装会装成 `link:`，改完代码重启宿主即生效 |
+| 会话里 | 让 agent 调用 `plugin_manager` 的 `install_bundle`，`target` 传目录绝对路径 |
+| CLI | `dsh plugin --profile <profile> add <目录或 tgz>`。Desktop 的 profile 由 App 管理，命令行装进 `profiles/web` 不会出现在 Desktop |
+
+装完在 **Plugins** 页确认 Grove 这一条出现，并在新会话里让模型调用 `grove_role`——工具真的注册上才算装好。
+
+### 独立 profile 试用（不碰日常配置）
+
+```sh
+export GROVE_VAULT="/absolute/path/to/Obsidian vault"
+npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove add "$PWD"
+npx --yes @deepseek-ai/dsh@0.2.2-rc.3 --profile grove
+```
+
+独立配置只初始化一次；已有 `grove` 配置时直接安装或启动。用独立配置试用，确保宿主的 Bash、文件编辑、通用自动化和其他扩展无法访问 vault 或代你运行本地确认命令。Grove 自身的模型工具只有角色提示、草稿和白名单查询。普通 Harness 会话仍遵循宿主的模型路由、权限和历史保留设置。
+
+### 命令行工具
+
+`grove` 命令来自包里的 `bin`，要全局安装才有；把插件装进某个 profile **不会**把它加进 PATH：
+
+```sh
+npm pack --pack-destination /tmp
+npm install --global /tmp/dsh-grove-0.1.2.tgz
+```
+
+## 日常使用
+
+1. 终端执行 `grove capture --body '为什么组织扩大后协调成本会上升？'`。在 Obsidian 中打开 vault 的 `Grove` 文件夹可看到 Markdown 笔记。
+2. 在 Harness 中自由对话。可要求使用 `grove_role` 作为思想伙伴、知识助手、研究助手、批判性审查者或创造助手。想保留一段讨论时，请求 `grove_propose` 起草，并提供你愿意保存的会话引用。探索可以直接结束。
+3. 在自己的终端执行 `grove preview 草稿ID`。用 `grove accept 草稿ID` 查看并输入 `SAVE`，或执行 `grove discard 草稿ID`。确认时也可用 `--file` 提供你编辑过的正文。
+4. 用 `grove list` 查询资产，用 `grove show 资产ID --version 1` 回看具体版本。默认 Grove 不向模型提供资产正文。若希望分享指定笔记，启动宿主前将 `GROVE_READABLE_IDS` 设为逗号分隔的资产 ID。取消分享后重新启动宿主。已进入宿主会话的内容仍受宿主历史设置约束。
+
+## 基础研究
+
+```sh
+grove add question --body '团队规模如何影响决策效率？'
+grove add research --question QUESTION_ID --body '比较决策权限和协调成本'
+grove add evidence --body '粘贴可核对的摘录' --source 'https://example.org/report' --locator '第12页第2段'
+grove add claim --body '我目前的判断'
+grove update CLAIM_ID --version 1 --link EVIDENCE_ID --relation supports
+grove update RESEARCH_ID --version 1 --link CLAIM_ID --relation related
+grove update RESEARCH_ID --version 2 --stage analysis
+grove update RESEARCH_ID --version 3 --stage review --status closed
+```
+
+把示例 ID 替换成上一步返回的 ID。阶段可回退，问题和项目可暂停、重开或归档。证据关系可表达支持、反驳和限定，双链指向具体版本。重写观点正文时，旧证据关系留在原版本，用户可以为新版本重新采用证据。结束研究时，成果可选。
+
+## 数据和卸载
+
+`Grove/` 内的版本文件使用 YAML 属性、Markdown 正文和 Obsidian 双链。Grove 不读 vault 中其他笔记。复制整个 `Grove/` 文件夹即可备份或迁移，点号开头的草稿文件也会随整目录迁移。可在 Obsidian 阅读及编辑正文，保留文件名和 Grove 元数据。要保留更改前的版本，使用 `grove update`。本版证据使用用户填写的来源标识与定位。当前能力的边界见[插件详情](docs/DETAIL.zh.md)。
+
+用 `npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove remove dsh-grove` 卸载宿主插件。数据留在 vault，终端命令可通过 `npm uninstall --global dsh-grove` 单独卸载。
+
+## 品牌资产
+
+标志、锁定组合、色板、字体与导出图都在 [`brand/`](brand/README.md)，规范见 [`brand/VI.md`](brand/VI.md)（中文）与 [`brand/VI.en.md`](brand/VI.en.md)（English）。根目录的 `icon.svg` 与 `brand/mark.svg` 保持字节一致，由测试保证。
+
+## 参与开发
+
+规则只有一份：[`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`。
+
+理念、任务分层、DoD 与评审清单在 [`docs/development/`](docs/development/README.md)；会话交接在 [`docs/journal/`](docs/journal/)。改动前先跑 `npm test` 与 `bash scripts/check-compat.sh`。
+
+## 从源代码验证
+
+```sh
+npm ci
+npm test
+npm pack
+```

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: grove
+      name: dsh-grove

package/docs/DETAIL.en.md

@@ -0,0 +1,41 @@
+# Grove
+
+Grove connects DeepSeek Harness and Obsidian to help you build knowledge you can revisit and revise, and develop your own judgment over time. The current plugin supports open-ended exploration, user-confirmed saves, and basic research.
+
+- **Explore freely and pursue research when it serves you.** Start with a passing idea and stop whenever you like. Keep an open question for later and decide whether to develop it into a project or a finished work.
+- **Keep the evidence and the history of your thinking.** Record where evidence came from and link it to the version of a claim it supports, challenges, or qualifies. Revisit that record when your judgment changes.
+- **Think with AI and stay in control of your knowledge.** AI can ask questions, offer other explanations, and draft notes. You decide what to adopt, save, and share. Your saved knowledge lives in your own Obsidian vault as Markdown.
+
+## What it provides
+
+Three model tools, registered inside the host:
+
+| Tool | Purpose | Boundary |
+| --- | --- | --- |
+| `grove_role` | Returns the collaboration guidance for a role you named explicitly (`thinking` / `knowledge` / `research` / `critical` / `creation`) | Read-only text; never touches the vault |
+| `grove_propose` | Drafts one proposal from your request and writes it as `.proposal.json` | Does not create an asset; only `grove accept` in your terminal saves it |
+| `grove_read` | Reads one asset you explicitly shared | Only IDs listed in `GROVE_READABLE_IDS` |
+
+There are ten asset types: inspiration, question, concept, theory, claim, evidence, method, output, exploration and research. Research projects and evidence are recorded through the terminal commands; the model may only draft the other types.
+
+## How to use it
+
+1. Configure the vault: the plugin config field `vault`, or the `GROVE_VAULT` environment variable. It must be an **absolute path to a real directory**; symlinks in the path are rejected.
+2. Talk to the agent; ask it to call `grove_role` when you want a different way of collaborating.
+3. To keep part of a discussion, ask it to call `grove_propose`, passing the conversation reference you want saved as `origin`.
+4. In your terminal, `grove preview <draft-id>` to review, `grove accept <draft-id>` and type `SAVE` to save, or `grove discard <draft-id>`.
+5. `grove list` / `grove show <asset-id> --version <N>` to look back; `grove update` writes a new version and leaves the old version's evidence links on it.
+
+## Where the data lives
+
+Everything is under `<vault>/Grove/`: one file per asset, `<id>.v<version>.md`, with YAML frontmatter, a Markdown body and Obsidian wikilinks; dot-prefixed `.proposal.json` files beside them are drafts. There is no database — copying the whole `Grove/` folder is the backup and the migration.
+
+## Known limitations
+
+- Evidence records only the source identifier and locator you type (`--source` / `--locator`). No attachment management, no automatic session locating.
+- No dedicated Web UI: the surface is the in-session tools plus the terminal CLI.
+- Saving must happen in an interactive terminal (`grove accept` asks you to type `SAVE`); the model cannot save on your behalf.
+- Asset bodies are not given to the model by default; sharing requires `GROVE_READABLE_IDS` in advance, and turning sharing off needs a host restart.
+- One note is capped at 1 MiB and a draft body at 128 KiB; `grove_read` refuses assets outside the sharing list and archived assets.
+- The `grove` command comes from the package's `bin` and needs a global install; installing the plugin into a profile does not put it on `PATH`.
+- Compatible with dsh `>=0.2.2-rc.1 <0.3.0`.

package/docs/DETAIL.zh.md

@@ -0,0 +1,41 @@
+# Grove（知林）
+
+Grove 是连接 DeepSeek Harness 与 Obsidian 的个人知识成长插件，帮助你积累可回看、可修正的知识，在长期探索中形成自己的判断。当前版本支持自由探索、自主保存和基础研究。
+
+- **自由探索，按需研究。** 从一个念头开始，随时停下。你可以留下开放问题，等值得深究时再开展研究，成果由你决定。
+- **保留依据和修订过程。** 记录证据出处，把支持、反驳或限定的证据连到具体版本，以便重查和修正判断。
+- **AI 协助思考，你掌握判断和知识。** AI 可以追问、提出不同解释和起草。你决定采纳、保存和分享什么，留下的知识以 Markdown 保存在自己的 Obsidian vault 中。
+
+## 提供什么
+
+三个模型工具，注册在宿主内：
+
+| 工具 | 作用 | 边界 |
+| --- | --- | --- |
+| `grove_role` | 返回你明确点名的协作角色指引（`thinking` / `knowledge` / `research` / `critical` / `creation`） | 只读文本，不碰 vault |
+| `grove_propose` | 按你的要求起草一条草稿，写成 `.proposal.json` | 不创建资产；要你在终端执行 `grove accept` 才落盘 |
+| `grove_read` | 读取一条你显式分享的资产 | 只认 `GROVE_READABLE_IDS` 白名单里的 ID |
+
+资产类型共十种：灵感、问题、概念、理论、判断、证据、方法、成果、探索、研究。研究与证据走终端命令，模型只能起草其余类型。
+
+## 怎么用
+
+1. 配置 vault：插件配置里的 `vault`，或环境变量 `GROVE_VAULT`。必须是**绝对路径的真实目录**；路径里的 symlink 会被拒绝。
+2. 在会话里对话，需要时让模型调用 `grove_role` 切换协作方式。
+3. 想留下讨论时，让模型调用 `grove_propose` 起草，并把你要保存的会话引用作为 `origin` 传入。
+4. 在终端 `grove preview <草稿ID>` 看内容，`grove accept <草稿ID>` 并输入 `SAVE` 落盘，或用 `grove discard` 丢弃。
+5. `grove list` / `grove show <资产ID> --version <N>` 回看；`grove update` 写入新版本，旧版本的证据关系留在旧版本上。
+
+## 数据放在哪
+
+全在 `<vault>/Grove/`：一条资产一个文件 `<id>.v<版本>.md`，YAML frontmatter + Markdown 正文 + Obsidian 双链；点号开头的 `.proposal.json` 是同目录的草稿。没有数据库，复制整个 `Grove/` 就是备份和迁移。
+
+## 已知限制
+
+- 证据只记录你填写的来源标识与定位（`--source` / `--locator`），没有附件管理，也不自动定位会话。
+- 没有专用 Web 界面：交互面是会话里的工具加终端 CLI。
+- 保存必须在交互式终端完成（`grove accept` 要手输 `SAVE`），模型不能代你落盘。
+- 默认不把资产正文交给模型；分享要预先设置 `GROVE_READABLE_IDS`，取消分享后需重启宿主。
+- 单条笔记上限 1 MiB，草稿正文上限 128 KiB；`grove_read` 拒绝白名单外和已归档的资产。
+- `grove` 命令来自 npm 全局安装的 `bin`；把插件装进某个 profile 不会把它加进 PATH。
+- 兼容 dsh `>=0.2.2-rc.1 <0.3.0`。

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36">
+  <g transform="translate(18 18) scale(1.12) translate(-18.6 -20.9)">
+    <path d="M16.9 30.4h2.2l-.65-12.3h-.9z" fill="#1B3A2E"/>
+    <path d="M18.4 19c2.2-6.5 8.3-9.4 10.5-8.15-1 5.3-4.9 8.45-10.5 8.15Z" fill="#2F7D5B"/>
+    <path d="M17.6 23c-2.2-5.1-6.5-7.3-8.5-6.3.7 4.1 4.3 6.3 8.5 6.3Z" fill="#5FA37E"/>
+    <path d="M15.4 31.5h5.2" stroke="#C98A3B" stroke-width="2.2" stroke-linecap="round" fill="none"/>
+  </g>
+</svg>

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Grove",
+    "description": "Explore with AI in DeepSeek Harness and pursue research with traceable evidence. You choose what to save and share. Keep knowledge you can revisit and revise in your own Obsidian vault.",
+    "detail": "docs/DETAIL.en.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Grove（知林）",
+    "description": "在 DeepSeek Harness 中与 AI 自由探索，按需开展有据可查的研究。你决定保存和分享什么，知识以可回看、可修正的 Markdown 笔记留在自己的 Obsidian vault。",
+    "detail": "docs/DETAIL.zh.md"
+  }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "dsh-grove",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Explore with AI in DeepSeek Harness and grow knowledge you can revisit and revise in your own Obsidian vault",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/plugin.js",
+  "exports": {
+    ".": "./src/plugin.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "icon": "icon.svg",
+  "bin": {
+    "grove": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "docs/DETAIL.en.md",
+    "docs/DETAIL.zh.md"
+  ],
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.2.2-rc.1 <0.3.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1 <0.3.0",
+    "semver": "^7.7.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1 <0.3.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { createInterface } from 'node:readline/promises'
+import { readFile } from 'node:fs/promises'
+import { Vault, stages, types } from './vault.js'
+import { accept, discard, preview } from './proposals.js'
+
+const usage = `Grove v0.1 · set GROVE_VAULT to an absolute Obsidian vault path
+  grove capture --body 'idea'
+  grove add TYPE --body 'text' [--title 'title'] [--origin 'session or source']
+  grove add evidence --body 'excerpt' --source 'source URL or identifier' --locator 'p. 12'
+  grove add research --body 'scope' --question QUESTION_ID
+  grove list [--query 'term']
+  grove show ID [--version N]
+  grove update ID --version N [--body 'new text'] [--status open|paused|closed|archived]
+  grove update ID --version N --stage STAGE
+  grove update ID --version N --link TARGET_ID --relation supports|refutes|qualifies|related|derived
+  grove preview DRAFT_ID
+  grove discard DRAFT_ID
+  grove accept DRAFT_ID [--body 'edited text' | --file FILE]
+Types: ${types.join(', ')}
+Research stages: ${stages.join(', ')}
+Use --file instead of --body for multiline text.
+`
+
+function print(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + '\n')
+}
+
+async function main() {
+  const { positionals: [command, id, ...extra], values } = parseArgs({
+    allowPositionals: true,
+    options: Object.fromEntries(['body', 'file', 'title', 'origin', 'source', 'locator', 'question', 'query', 'version', 'status', 'stage', 'link', 'relation'].map(name => [name, { type: 'string' }])),
+  })
+  if (!command || command === 'help') return process.stdout.write(usage)
+  if (extra.length) throw new Error('Unexpected positional arguments')
+  if (values.body !== undefined && values.file !== undefined) throw new Error('Specify either --body or --file')
+  const vault = new Vault(process.env.GROVE_VAULT)
+  const body = values.file === undefined ? values.body : await readFile(values.file, 'utf8')
+  const version = values.version === undefined ? undefined : Number(values.version)
+  switch (command) {
+    case 'capture': return print(await vault.create({ ...values, body, type: 'inspiration' }))
+    case 'add': return print(await vault.create({ ...values, body, type: id }))
+    case 'list': return print((await vault.list(values.query)).map(({ meta }) => meta))
+    case 'show': return print(await vault.get(id, version))
+    case 'update': {
+      if (!Number.isSafeInteger(version) || version < 1) throw new Error('Provide the current --version')
+      if (!body && !values.status && !values.stage && !values.link) throw new Error('Provide a change')
+      const link = values.link ? { id: values.link, kind: values.relation } : undefined
+      return print(await vault.update(id, version, { ...values, body, link }))
+    }
+    case 'preview': return print(await preview(vault, id))
+    case 'discard': return discard(vault, id)
+    case 'accept': {
+      if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('Acceptance requires an interactive terminal')
+      const proposal = await preview(vault, id)
+      if (body !== undefined) proposal.body = body
+      print(proposal)
+      const terminal = createInterface({ input: process.stdin, output: process.stdout })
+      try {
+        if ((await terminal.question('Type SAVE to create this asset: ')) !== 'SAVE') {
+          return process.stdout.write('Cancelled. No asset created.\n')
+        }
+        return print(await accept(vault, id, proposal))
+      } finally {
+        terminal.close()
+      }
+    }
+    default: throw new Error('Unknown command; run grove help')
+  }
+}
+main().catch(error => {
+  process.stderr.write(`${error.message}\n`)
+  process.exitCode = 1
+})

package/src/plugin.js

@@ -0,0 +1,55 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { Vault, types } from './vault.js'
+import { propose, roles } from './proposals.js'
+
+export const name = 'grove'
+export const inject = ['tools']
+
+const output = {
+  schema: { type: 'string' },
+  render: (_args, value) => [{ type: 'text', text: value }],
+}
+
+export function apply(ctx, config = {}) {
+  const path = config.vault ?? process.env.GROVE_VAULT
+  if (!path) return
+  const vault = new Vault(path)
+  const allowed = new Set(config.readableIds ?? (process.env.GROVE_READABLE_IDS ?? '').split(',').map(id => id.trim()).filter(Boolean))
+
+  ctx.tools.register(defineTool({
+    name: 'grove_role',
+    description: 'Get the Grove collaboration guidance for a role explicitly requested by the user.',
+    parameters: { role: { type: 'string', enum: Object.keys(roles), required: true } },
+    output,
+    execute: ({ role }) => roles[role],
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'grove_propose',
+    description: 'When asked, save a draft for local human review. This tool does not create a knowledge asset.',
+    parameters: {
+      type: { type: 'string', enum: types.filter(type => !['evidence', 'research'].includes(type)), required: true },
+      body: { type: 'string', required: true },
+      title: { type: 'string' },
+      origin: { type: 'string', description: 'User-approved session reference or source description' },
+    },
+    output,
+    async execute(args) {
+      const id = await propose(vault, args)
+      return `Draft ${id}. The user can review it with grove preview ${id} in their terminal.`
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'grove_read',
+    description: 'Read one explicitly shared Grove asset by ID.',
+    parameters: { id: { type: 'string', required: true } },
+    output,
+    async execute({ id }) {
+      if (!allowed.has(id)) return 'This asset is outside the configured Grove sharing scope.'
+      const { meta, body } = await vault.get(id)
+      if (meta.status === 'archived') return 'This asset is archived.'
+      return JSON.stringify({ id, version: meta.version, title: meta.title, type: meta.type, body, source: meta.source, locator: meta.locator })
+    },
+  }))
+}

package/src/proposals.js

@@ -0,0 +1,59 @@
+import { randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { open, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { types } from './vault.js'
+
+export const roles = {
+  thinking: 'Clarify the question, expose assumptions, and offer alternative explanations.',
+  knowledge: 'Explain concepts, compare examples, and distinguish the user’s understanding from references.',
+  research: 'Identify research questions, methods, evidence gaps, and traceable sources.',
+  critical: 'Seek counterexamples and alternative explanations. Separate evidence from speculation.',
+  creation: 'Help structure the user’s argument and preserve source references. Produce a draft only on request.',
+}
+
+async function draftFile(vault, id, write = false) {
+  if (typeof id !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(id)) throw new Error('Invalid proposal ID')
+  const directory = await vault.folder(write)
+  const flags = write ? constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL
+    : constants.O_RDONLY | constants.O_NONBLOCK
+  return open(join(directory, `.${id}.proposal.json`), flags | constants.O_NOFOLLOW, 0o600)
+}
+
+export async function propose(vault, input) {
+  const { type, title, body, origin } = input
+  if (!types.includes(type) || ['research', 'evidence'].includes(type)) throw new Error('Unsupported proposal type')
+  if (typeof body !== 'string' || !body.trim() || Buffer.byteLength(body) > 128 * 1024) throw new Error('Invalid proposal body')
+  if (title && (typeof title !== 'string' || title.length > 300)) throw new Error('Invalid proposal title')
+  if (origin && (typeof origin !== 'string' || origin.length > 2000)) throw new Error('Invalid proposal origin')
+  const id = randomUUID()
+  const handle = await draftFile(vault, id, true)
+  try {
+    await handle.writeFile(JSON.stringify({ type, title, body, origin }))
+  } finally {
+    await handle.close()
+  }
+  return id
+}
+
+export async function preview(vault, id) {
+  const handle = await draftFile(vault, id)
+  try {
+    const stat = await handle.stat()
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error('Invalid proposal file')
+    return JSON.parse(await handle.readFile('utf8'))
+  } finally {
+    await handle.close()
+  }
+}
+
+export async function accept(vault, id, proposal) {
+  const note = await vault.create({ ...proposal, origin: proposal.origin ? `AI draft confirmed by user · ${proposal.origin}` : 'AI draft confirmed by user' }, id)
+  await discard(vault, id).catch(error => { if (error.code !== 'ENOENT') throw error })
+  return note
+}
+
+export async function discard(vault, id) {
+  await preview(vault, id)
+  await unlink(join(await vault.folder(), `.${id}.proposal.json`))
+}

package/src/vault.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, realpath, mkdir, open, link, unlink, readdir } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+import { parse, stringify } from 'yaml'
+
+export const types = ['inspiration', 'question', 'concept', 'theory', 'claim', 'evidence', 'method', 'output', 'exploration', 'research']
+export const stages = ['question', 'framework', 'evidence', 'analysis', 'judgment', 'validation', 'expression', 'review']
+const relations = ['related', 'derived', 'supports', 'refutes', 'qualifies']
+const validId = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/
+const filename = /^([a-f0-9-]{36})\.v([1-9][0-9]*)\.md$/
+const maxBytes = 1024 * 1024
+
+function required(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} is required`)
+  return value.trim()
+}
+
+async function directory(path, create) {
+  if (create) await mkdir(path).catch(error => { if (error.code !== 'EEXIST') throw error })
+  const stat = await lstat(path)
+  if (!stat.isDirectory() || await realpath(path) !== path) throw new Error('Grove requires a real directory')
+  return path
+}
+
+function encode(meta, body) {
+  const links = [
+    ...(meta.question ? [`[[${meta.question}.v${meta.questionVersion ?? 1}]]`] : []),
+    ...(meta.links ?? []).map(item => `${item.kind} [[${item.id}.v${item.version}]]`),
+  ]
+  return `---\n${stringify(meta, { lineWidth: 0 })}---\n\n${body}\n${links.length ? `\n<!-- grove-links -->\n${links.join('\n')}\n` : ''}`
+}
+
+async function readNote(path, id, version) {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try {
+    const stat = await handle.stat()
+    if (!stat.isFile() || stat.size > maxBytes) throw new Error('Invalid Grove note file')
+    const raw = await handle.readFile('utf8')
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(raw)
+    if (!match) throw new Error('Invalid Grove Markdown frontmatter')
+    const meta = parse(match[1], { maxAliasCount: 0 })
+    if (!meta || meta.id !== id || meta.version !== version || !types.includes(meta.type)) {
+      throw new Error('Grove note metadata does not match its filename')
+    }
+    return { meta, body: match[2].split('\n<!-- grove-links -->\n')[0].trim() }
+  } finally {
+    await handle.close()
+  }
+}
+
+async function publish(path, target, content) {
+  if (Buffer.byteLength(content) > maxBytes) throw new Error('Grove note exceeds the size limit')
+  const temp = join(path, `.${randomUUID()}.tmp`)
+  const handle = await open(temp, 'wx', 0o600)
+  try {
+    try {
+      await handle.writeFile(content)
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    await link(temp, target)
+  } finally {
+    await unlink(temp)
+  }
+}
+
+export class Vault {
+  constructor(path) {
+    if (typeof path !== 'string' || !isAbsolute(path)) throw new Error('Set GROVE_VAULT to an absolute vault path')
+    this.path = path
+  }
+
+  async folder(create = false) {
+    return directory(join(await realpath(this.path), 'Grove'), create)
+  }
+
+  async inventory() {
+    const path = await this.folder().catch(error => {
+      if (error.code === 'ENOENT') return null
+      throw error
+    })
+    const entries = new Map()
+    for (const name of path ? await readdir(path) : []) {
+      const match = filename.exec(name)
+      if (!match || !validId.test(match[1])) continue
+      const version = Number(match[2])
+      if (!Number.isSafeInteger(version)) continue
+      const versions = entries.get(match[1]) ?? []
+      versions.push(version)
+      entries.set(match[1], versions)
+    }
+    return entries
+  }
+
+  async get(id, version) {
+    if (typeof id !== 'string' || !validId.test(id)) throw new Error('Invalid Grove ID')
+    const selected = version ?? Math.max(...((await this.inventory()).get(id) ?? []))
+    if (!Number.isSafeInteger(selected) || selected < 1) throw new Error('Grove note not found')
+    return readNote(join(await this.folder(), `${id}.v${selected}.md`), id, selected)
+  }
+
+  async list(query = '') {
+    const entries = await this.inventory()
+    const notes = await Promise.all([...entries].map(([id, versions]) => this.get(id, Math.max(...versions))))
+    const needle = query.toLowerCase()
+    return notes.filter(({meta, body}) => `${meta.title}\n${meta.type}\n${body}`.toLowerCase().includes(needle))
+  }
+
+  async create(input, id = randomUUID()) {
+    if (!validId.test(id)) throw new Error('Invalid Grove ID')
+    const type = input.type
+    if (!types.includes(type)) throw new Error('Unknown asset type')
+    const body = required(input.body, 'body')
+    const meta = { grove: 1, id, version: 1, type, title: input.title?.trim() || body.split('\n')[0].slice(0, 100), created: new Date().toISOString() }
+    if (input.origin) meta.origin = required(input.origin, 'origin')
+    if (type === 'question' || type === 'research') meta.status = 'open'
+    if (type === 'research') {
+      const question = await this.get(input.question)
+      if (question.meta.type !== 'question') throw new Error('Research requires a question')
+      meta.question = question.meta.id
+      meta.questionVersion = question.meta.version
+      meta.stage = stages[0]
+    }
+    if (type === 'evidence') {
+      meta.source = required(input.source, 'source')
+      meta.locator = required(input.locator, 'locator')
+    }
+    const path = await this.folder(true)
+    await publish(path, join(path, `${id}.v1.md`), encode(meta, body))
+    return { meta, body }
+  }
+
+  async update(id, expected, change) {
+    const note = await this.get(id)
+    if (note.meta.version !== expected) throw new Error('Version conflict; read the latest note and retry')
+    const { meta } = note
+    let body = note.body
+    if (change.body !== undefined) {
+      body = required(change.body, 'body')
+      if (meta.type === 'claim' && body !== note.body) {
+        meta.links = (meta.links ?? []).filter(edge => !['supports', 'refutes', 'qualifies'].includes(edge.kind))
+      }
+    }
+    if (change.status !== undefined) {
+      const allowed = meta.type === 'question' || meta.type === 'research'
+        ? ['open', 'paused', 'closed', 'archived'] : ['active', 'archived']
+      if (!allowed.includes(change.status)) throw new Error('Invalid status for this asset')
+      meta.status = change.status
+    }
+    if (change.stage !== undefined) {
+      if (meta.type !== 'research' || !stages.includes(change.stage)) throw new Error('Invalid research stage')
+      meta.stage = change.stage
+    }
+    if (change.link) {
+      const { kind, id: targetId, version } = change.link
+      if (!relations.includes(kind)) throw new Error('Invalid relationship')
+      const target = await this.get(targetId, version)
+      if (targetId === id) throw new Error('An asset cannot link to itself')
+      if (['supports', 'refutes', 'qualifies'].includes(kind) && (meta.type !== 'claim' || target.meta.type !== 'evidence')) {
+        throw new Error('Evidence relations must run from a claim to evidence')
+      }
+      const edge = { kind, id: targetId, version: target.meta.version }
+      if (!(meta.links ?? []).some(link => link.kind === kind && link.id === targetId && link.version === edge.version)) {
+        meta.links = [...(meta.links ?? []), edge]
+      }
+    }
+    meta.version++
+    meta.modified = new Date().toISOString()
+    const path = await this.folder()
+    try {
+      await publish(path, join(path, `${id}.v${meta.version}.md`), encode(meta, body))
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new Error('Version conflict; read the latest note and retry')
+      throw error
+    }
+    return { meta, body }
+  }
+}