Skip to main content
Z

dsh-ai-collab

zhuyw3927/dsh-ai-collab

Gives every AI tool in a repository one shared project memory: an append-only .ai/ work log, a current-state snapshot, and a zoned AGENTS.md whose user zone automation never overwrites. Windows only.

Install

dsh plugin --profile web add github:zhuyw3927/dsh-ai-collab

README

dsh-ai-collab

ci

A DeepSeek Harness bundle that adds a project-agnostic AI collaboration layer built around two ideas:

  • AGENTS.md — the single entry file at the project root (facts: build/flash commands, constraints, read-only dirs);
  • .ai/ — one hidden folder holding an append-only work log, a current-state snapshot, a JSON schema and archive.

The point: any AI tool working in the repo (DSH, Claude Code, Cursor, Copilot, Codex) reads and writes the same progress, instead of rediscovering the project every session.

Status: 0.4.3, experimental. Published on npm as dsh-ai-collab; not yet listed in the community plugin market — see Known limitations.

Requirements

DeepSeek Harness0.2.1+ (tested on 0.2.2-rc.3; the dsh/Cordis plugin API this bundle targets)
Node.js>= 20 (bundled Electron Node works)
OSWindows 10/11 only for now (scaffolding runs Windows PowerShell 5.1; the read-only tools are OS-independent, but macOS/Linux are not supported or tested)

Install

Option A — Creator mode (recommended)

plugin_manager
  action: install_bundle
  target: <absolute path to this package>

Option B — CLI

dsh plugin --profile desktop add "F:\path\to\dsh-ai-collab"
# then append "dsh-ai-collab" to dsh.profile.bundles in
#   %USERPROFILE%\.dsh\profiles\desktop\package.json

Option C — local absolute path (legacy, not recommended)

Older hosts accepted a raw absolute-path row in the profile patch. On current builds this does not mount reliably; use the bundle install above. The patch form is kept only for isolated debugging:

Add to $DSH_HOME/profiles/desktop/cordis.patch.yml:

- insert:
    - id: ai-collab
      name: F:\path\to\dsh-ai-collab\index.js
      config:
        autoInit: true

Patch loading converts absolute paths to file URLs, so no pnpm install is needed. Remove the block to roll back.

Restart the app. The profile's sessions (the GUI uses desktop) then expose the tools below.

Plugin market

Release and submission steps live in docs/MARKET.md: npm publish, the awesome-dsh-plugin PR (the community market catalog), and an optional self-hosted format-1 index generated by scripts/make-market-index.mjs.

Configuration

config keys are read as-is (no Config schema yet, so values are not type-checked); all keys optional:

KeyDefaultMeaning
autoInitfalseOn session/created, run ai-ensure in the session cwd unless it is a temp/system directory: scaffold .ai/, refresh AGENTS.md and the board
maxTail10How many recent log records ai_status returns
initScriptpackaged ai-ensure.ps1Override the ensure script

Tools

ToolDoes
ai_statusReads .ai/status.json + the last N log records (start a session here)
ai_logAppends one record to .ai/log.jsonl; rejects invalid enums, requires issue for blocked/failed; refreshes status.json and the sibling board
ai_checkValidates every record: required fields, enums, timezone, monotonic ts, unique id
ai_boardRead-only roll-up of sibling projects' .ai/status.json
ai_initEnsures the workspace: scaffold if missing, refresh stale .ai//AGENTS.md, refresh stale board (idempotent)

What ai_init creates

<project root>
├─ AGENTS.md              ← only visible file (facts + discipline pointer)
└─ .ai\
   ├─ llm.ps1, llm.cmd    ← CLI: status / tail / add / check / entries / archive / board / doctor
   ├─ log.jsonl           ← append-only, UTF-8 no BOM, LF
   ├─ status.json         ← current state (overwritten)
   ├─ LOG_FORMAT.md, SECURITY.md, schema\log.schema.json
   ├─ changelog\          ← version-level docs + patch engine
   ├─ entries\            ← forwarding-file masters (publish on demand)
   └─ _archive\

Record shape (one JSON object per line):

{"id":"...","ts":"2026-11-04T17:10:00+08:00","tool":"claude-code","actor":"ai",
 "action":"fix","status":"ok","summary":"what changed + result",
 "files_modified":["src/a.c"],"verification":"rebuild 0/0, Code=78106"}

status ∈ ok|partial|blocked|todo|failed; action ∈ task_start|task_done|fix|diagnosis|build|commit|doc|review|rollback|correction|maintenance|handoff.

Updating (after install)

The bundle is an npm package mounted into a profile. The Host loads it at boot and ships no HMR/watcher, so code changes take effect only after a restart.

  1. Bump version in package.json (e.g. 0.2.0 → 0.2.1) so you can tell what is live.
  2. Reinstall from the same path (or a new version): dsh plugin --profile desktop add "F:\path\to\dsh-ai-collab", or run Creator-mode install_bundle again.
  3. Restart the app. Every session in that profile then uses the new code on its next turn.
  4. Existing projects keep their own copied .ai/ files. The next ai-ensure (or an ai_init tool call) sees a changed framework hash and refreshes .ai/ + AGENTS.md automatically; projects you never revisit stay on the old copy until then.
  5. Global $DSH_HOME/AGENTS.md is independent of this bundle: editing it applies to the next request immediately, with no restart.

Verifying an install

Two append-only files under $DSH_HOME/logs record what actually happened at boot:

Get-Content "$DSH_HOME\logs\ai-collab-boot.log" -Tail 3     # version=… autoInit=… home=env|homedir
Get-Content "$DSH_HOME\logs\ai-collab-tools.log" -Tail 3   # tools=ai_status,… spec=file:///…/app.asar/…
  • A fresh boot line means apply() ran in this process.
  • A tools= line means all five tools registered; spec shows where @deepseek-ai/dsh-tools was loaded from.
  • load-failed / register-failed lines carry the exact resolution errors.

The plugin is mounted from outside app.asar (a link:/absolute path), so the bare @deepseek-ai/dsh-tools specifier is not resolvable; it is loaded from the host's real app.asar path instead (see asarRoots() in index.js). DSH_HOME is read from the host environment and may be absent when the app is launched from Explorer — the plugin then falls back to ~/.dsh (home=homedir).

AGENTS.md zones: generated vs project-owned

AGENTS.md is split into two marked zones:

<!-- dsh-ai-collab:generated:start -->   … template maintened (routing, permissions, commands) …
<!-- dsh-ai-collab:generated:end -->

<!-- dsh-ai-collab:user:start -->        … project facts, sampling data, analysis methods, decisions …
<!-- dsh-ai-collab:user:end -->
  • ai_log (and ai_init/ai-ensure) refresh the task list (TASKS.md) whenever the workspace has .ai/tasks-enabled.
  • Re-render replaces only the generated zone. The user zone (and anything outside both zones) is preserved byte-for-byte; placeholders.json, log.jsonl and status.json are never touched.
  • A file without the zone markers is treated as project-owned and is never rewritten; the rendered reference goes to .ai/AGENTS.generated.md. This includes legacy single-line-marker files, which are frozen.
  • Explicit migration only:
    • -ForceAgents — rebuild the generated zone and move the whole old file into the user zone (nothing deleted);
    • -ResetAgents — discard old content and write the template (destructive, explicit).

Safety

  • The log is append-only; corrections are new records (action:"correction"), never edits.
  • autoInit writes only into project-like working directories, never into %TEMP% or read-only trees.
  • No credentials expected in the log; a SECURITY.md in .ai/ describes where secrets go (.ai/private/).
  • The scaffold is a normal PowerShell script you can read: ai-init.ps1 → install.ps1 → template/.ai/.
  • Task lists are rendered inside the plugin (lib/tasks.js); the plugin never executes a workspace-provided .ai/llm.ps1, so cloning a hostile repository and logging cannot run its code.

Uninstall

  1. Remove dsh-ai-collab from dsh.profile.bundles (or set enabled: false on its row) and restart.
  2. Optionally delete the package from the profile (dsh plugin --profile desktop remove dsh-ai-collab).
  3. Per-project .ai/ folders are plain files; delete at will.

Global discipline (user level)

The bundle ships tools and workspace scaffolding, not a user-level instruction file. To get the mandatory "step 0" behaviour in every session, copy AGENTS.global.template.md to $DSH_HOME/AGENTS.md (or merge it into your existing one). It contains only cross-project discipline — no project facts.

Development

npm run check     # node --check index.js + lib/*.js
npm test          # 19 tests: tool contract, config, task rendering, AGENTS.md preservation
npm pack --dry-run

Known limitations

  • Verified against the shipped @deepseek-ai/dsh-tools contract (0.2.2): parameters use the property-map DSL, output.render returns an array of content blocks, and the session workspace is resolved loosely through ctx.get('workingDirectory', false) with a process.cwd() fallback. Still run the preflight in your own DSH build if you modify these parts.
  • ai_init / autoInit are Windows-only (packaged PowerShell 5.1); the bundle is declared "os": ["win32"] and macOS/Linux are not supported yet. On other platforms the scaffold tools return unsupported-platform instead of failing silently.
  • Config values are normalised in-process (no schemastery Config yet); invalid values produce warnings in $DSH_HOME/logs/ai-collab-config.log.
  • A legacy AGENTS.md without zone markers is frozen by design; migrate explicitly with -ForceAgents or -ResetAgents.
  • The forwarding files for Claude Code / Gemini CLI are only masters under .ai/entries/; publish them with .ai\llm.cmd entries -Publish when a tool needs auto-discovery.
  • Publishing is not automated yet — see PUBLISH.md.

License

MIT — see LICENSE.

Related plugins