- Home
- Plugins
- Tools & Capabilities
- dsh-ai-collab
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-collabREADME
dsh-ai-collab
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 Harness | 0.2.1+ (tested on 0.2.2-rc.3; the dsh/Cordis plugin API this bundle targets) |
| Node.js | >= 20 (bundled Electron Node works) |
| OS | Windows 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:
| Key | Default | Meaning |
|---|---|---|
autoInit | false | On session/created, run ai-ensure in the session cwd unless it is a temp/system directory: scaffold .ai/, refresh AGENTS.md and the board |
maxTail | 10 | How many recent log records ai_status returns |
initScript | packaged ai-ensure.ps1 | Override the ensure script |
Tools
| Tool | Does |
|---|---|
ai_status | Reads .ai/status.json + the last N log records (start a session here) |
ai_log | Appends one record to .ai/log.jsonl; rejects invalid enums, requires issue for blocked/failed; refreshes status.json and the sibling board |
ai_check | Validates every record: required fields, enums, timezone, monotonic ts, unique id |
ai_board | Read-only roll-up of sibling projects' .ai/status.json |
ai_init | Ensures 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.
- Bump
versioninpackage.json(e.g.0.2.0→0.2.1) so you can tell what is live. - Reinstall from the same path (or a new version):
dsh plugin --profile desktop add "F:\path\to\dsh-ai-collab", or run Creator-modeinstall_bundleagain. - Restart the app. Every session in that profile then uses the new code on its next turn.
- Existing projects keep their own copied
.ai/files. The nextai-ensure(or anai_inittool call) sees a changed framework hash and refreshes.ai/+AGENTS.mdautomatically; projects you never revisit stay on the old copy until then. - Global
$DSH_HOME/AGENTS.mdis 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;specshows where@deepseek-ai/dsh-toolswas loaded from. load-failed/register-failedlines 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(andai_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.jsonlandstatus.jsonare 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. autoInitwrites only into project-like working directories, never into%TEMP%or read-only trees.- No credentials expected in the log; a
SECURITY.mdin.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
- Remove
dsh-ai-collabfromdsh.profile.bundles(or setenabled: falseon its row) and restart. - Optionally delete the package from the profile (
dsh plugin --profile desktop remove dsh-ai-collab). - 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-toolscontract (0.2.2): parameters use the property-map DSL,output.renderreturns an array of content blocks, and the session workspace is resolved loosely throughctx.get('workingDirectory', false)with aprocess.cwd()fallback. Still run the preflight in your own DSH build if you modify these parts. ai_init/autoInitare 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 returnunsupported-platforminstead of failing silently.- Config values are normalised in-process (no schemastery
Configyet); invalid values produce warnings in$DSH_HOME/logs/ai-collab-config.log. - A legacy
AGENTS.mdwithout zone markers is frozen by design; migrate explicitly with-ForceAgentsor-ResetAgents. - The forwarding files for Claude Code / Gemini CLI are only masters under
.ai/entries/; publish them with.ai\llm.cmd entries -Publishwhen a tool needs auto-discovery. - Publishing is not automated yet — see
PUBLISH.md.
License
MIT — see LICENSE.
Related plugins
archify (deepseek-harness)
tt-a1i/archify
WeKnora (dsh-weknora)
tencent/weknora
next-ai-draw-io (dsh-plugin)
dayuanjiang/next-ai-draw-io
weknora
tencent/weknora