agent-shared-workspace 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,385 @@
1
+ #!/usr/bin/env python3
2
+ """Zero-dependency MCP (Model Context Protocol) stdio server for Agent Shared Workspace.
3
+
4
+ Implements JSON-RPC 2.0 over stdio using Python's standard library only.
5
+ Delegates every operation to ``workspace_tool`` via subprocess so all commands
6
+ share identical CLI semantics and cross-process file locking.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import os
13
+ import subprocess
14
+ import sys
15
+ from pathlib import Path
16
+ from typing import Any
17
+
18
+ from . import __version__
19
+
20
+ PROTOCOL_VERSION = "2024-11-05"
21
+ CLI_MODULE = "agent_shared_workspace.cli"
22
+
23
+ TOOLS: list[dict[str, Any]] = [
24
+ {
25
+ "name": "workspace_init",
26
+ "description": "Idempotently initialize shared workspace skeleton docs, workspace.config.json, .gitignore, and Git.",
27
+ "inputSchema": {
28
+ "type": "object",
29
+ "properties": {
30
+ "lang": {"type": "string", "enum": ["zh", "en"], "default": "en", "description": "Language for skeleton docs."},
31
+ "no_git": {"type": "boolean", "default": False, "description": "Skip git init when true."},
32
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
33
+ },
34
+ },
35
+ },
36
+ {
37
+ "name": "workspace_status",
38
+ "description": "Show active projects and Git working tree status for the shared workspace.",
39
+ "inputSchema": {
40
+ "type": "object",
41
+ "properties": {
42
+ "guard": {"type": "boolean", "default": False, "description": "Return an error status if uncommitted changes exist."},
43
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
44
+ },
45
+ },
46
+ },
47
+ {
48
+ "name": "workspace_guard",
49
+ "description": "Check whether the shared workspace Git tree is clean. Returns an error if uncommitted changes remain.",
50
+ "inputSchema": {
51
+ "type": "object",
52
+ "properties": {
53
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
54
+ },
55
+ },
56
+ },
57
+ {
58
+ "name": "exp_search",
59
+ "description": "Search shared pitfall/experience memory by keyword, tag, or list all registered tags.",
60
+ "inputSchema": {
61
+ "type": "object",
62
+ "properties": {
63
+ "query": {"type": "string", "default": "", "description": "Keyword to match in index or entry body."},
64
+ "tags": {"type": "array", "items": {"type": "string"}, "description": "Optional tag filters (AND match)."},
65
+ "list_tags": {"type": "boolean", "default": False, "description": "When true, list all tags with counts."},
66
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
67
+ },
68
+ },
69
+ },
70
+ {
71
+ "name": "exp_get",
72
+ "description": "Read the index row and full body (or sunk path) of a specific EXP entry, e.g. EXP-001.",
73
+ "inputSchema": {
74
+ "type": "object",
75
+ "required": ["exp_id"],
76
+ "properties": {
77
+ "exp_id": {"type": "string", "description": "Experience ID such as EXP-001 or 001."},
78
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
79
+ },
80
+ },
81
+ },
82
+ {
83
+ "name": "exp_add",
84
+ "description": "Record a new verified experience/pitfall with automatic sequential ID and cross-process locking.",
85
+ "inputSchema": {
86
+ "type": "object",
87
+ "required": ["title"],
88
+ "properties": {
89
+ "title": {"type": "string", "description": "One-line conclusion or pitfall title."},
90
+ "exp_type": {"type": "string", "default": "踩坑+复用方法", "description": "Category label."},
91
+ "tags": {"type": "array", "items": {"type": "string"}, "description": "Optional classification tags."},
92
+ "phenomenon": {"type": "string", "default": "", "description": "Observed symptom and trigger condition."},
93
+ "cause": {"type": "string", "default": "", "description": "Verified root cause."},
94
+ "solution": {"type": "string", "default": "", "description": "Fix or reusable procedure."},
95
+ "criteria": {"type": "string", "default": "", "description": "Verification criteria."},
96
+ "sink": {"type": "string", "description": "Optional project ID/name to sink detailed body into."},
97
+ "agent": {"type": "string", "default": "mcp-agent", "description": "Recording agent name."},
98
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
99
+ },
100
+ },
101
+ },
102
+ {
103
+ "name": "exp_update",
104
+ "description": "Append new evidence or follow-up notes to an existing EXP entry without creating a duplicate.",
105
+ "inputSchema": {
106
+ "type": "object",
107
+ "required": ["exp_id", "note"],
108
+ "properties": {
109
+ "exp_id": {"type": "string", "description": "Experience ID such as EXP-001."},
110
+ "note": {"type": "string", "description": "Additional verified evidence or revision note."},
111
+ "agent": {"type": "string", "default": "mcp-agent", "description": "Recording agent name."},
112
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
113
+ },
114
+ },
115
+ },
116
+ {
117
+ "name": "project_list",
118
+ "description": "List all Project_XXX directories and the current highest project ID.",
119
+ "inputSchema": {
120
+ "type": "object",
121
+ "properties": {
122
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
123
+ },
124
+ },
125
+ },
126
+ {
127
+ "name": "project_new",
128
+ "description": "Create a new project directory following SOP and register it on the workspace board.",
129
+ "inputSchema": {
130
+ "type": "object",
131
+ "required": ["name"],
132
+ "properties": {
133
+ "name": {"type": "string", "description": "Short project name."},
134
+ "owner": {"type": "string", "default": "mcp-agent", "description": "Owner agent name."},
135
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
136
+ },
137
+ },
138
+ },
139
+ {
140
+ "name": "project_update",
141
+ "description": "Update a project's status in both its README and the global workspace board.",
142
+ "inputSchema": {
143
+ "type": "object",
144
+ "required": ["project", "status"],
145
+ "properties": {
146
+ "project": {"type": "string", "description": "Project number (e.g. 001) or name substring."},
147
+ "status": {"type": "string", "description": "Updated status text."},
148
+ "entry": {"type": "string", "description": "Optional updated continuation entry pointer."},
149
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
150
+ },
151
+ },
152
+ },
153
+ {
154
+ "name": "handoff_record",
155
+ "description": "Write a structured multi-agent handoff and atomically sync project README and workspace board.",
156
+ "inputSchema": {
157
+ "type": "object",
158
+ "required": ["project", "agent", "status", "done"],
159
+ "properties": {
160
+ "project": {"type": "string", "description": "Project number or name substring."},
161
+ "agent": {"type": "string", "description": "Agent name performing the handoff."},
162
+ "status": {"type": "string", "description": "Current project status summary."},
163
+ "done": {"type": "string", "description": "Completed items (newline-separated)."},
164
+ "evidence": {"type": "string", "default": "", "description": "Evidence paths or verification results."},
165
+ "todo": {"type": "string", "default": "", "description": "Remaining items and next steps."},
166
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
167
+ },
168
+ },
169
+ },
170
+ {
171
+ "name": "workspace_commit",
172
+ "description": "Commit shared workspace changes to local Git (automatically excludes .workspace.lock).",
173
+ "inputSchema": {
174
+ "type": "object",
175
+ "required": ["message"],
176
+ "properties": {
177
+ "message": {"type": "string", "description": "Git commit message."},
178
+ "workspace_root": {"type": "string", "description": "Optional override for AGENT_WORKSPACE_ROOT."},
179
+ },
180
+ },
181
+ },
182
+ ]
183
+
184
+
185
+ def _build_cli_args(tool_name: str, args: dict[str, Any]) -> list[str]:
186
+ if tool_name == "workspace_init":
187
+ cmd = ["init", "--lang", str(args.get("lang", "en"))]
188
+ if args.get("no_git"):
189
+ cmd.append("--no-git")
190
+ return cmd
191
+
192
+ if tool_name == "workspace_status":
193
+ cmd = ["status"]
194
+ if args.get("guard"):
195
+ cmd.append("--guard")
196
+ return cmd
197
+
198
+ if tool_name == "workspace_guard":
199
+ return ["guard"]
200
+
201
+ if tool_name == "exp_search":
202
+ cmd = ["exp", "search"]
203
+ if args.get("list_tags"):
204
+ cmd.append("--list-tags")
205
+ return cmd
206
+ query = str(args.get("query", "")).strip()
207
+ if query:
208
+ cmd.append(query)
209
+ for tag in args.get("tags") or []:
210
+ cmd.extend(["--tag", str(tag)])
211
+ return cmd
212
+
213
+ if tool_name == "exp_get":
214
+ return ["exp", "get", str(args["exp_id"])]
215
+
216
+ if tool_name == "exp_add":
217
+ cmd = ["exp", "add", "--title", str(args["title"])]
218
+ if args.get("exp_type"):
219
+ cmd.extend(["--type", str(args["exp_type"])])
220
+ for tag in args.get("tags") or []:
221
+ cmd.extend(["--tag", str(tag)])
222
+ for field in ("phenomenon", "cause", "solution", "criteria", "sink", "agent"):
223
+ val = args.get(field)
224
+ if val:
225
+ cmd.extend([f"--{field}", str(val)])
226
+ return cmd
227
+
228
+ if tool_name == "exp_update":
229
+ cmd = ["exp", "update", str(args["exp_id"]), "--note", str(args["note"])]
230
+ if args.get("agent"):
231
+ cmd.extend(["--agent", str(args["agent"])])
232
+ return cmd
233
+
234
+ if tool_name == "project_list":
235
+ return ["project", "list"]
236
+
237
+ if tool_name == "project_new":
238
+ cmd = ["project", "new", str(args["name"])]
239
+ if args.get("owner"):
240
+ cmd.extend(["--owner", str(args["owner"])])
241
+ return cmd
242
+
243
+ if tool_name == "project_update":
244
+ cmd = ["project", "update", str(args["project"]), "--status", str(args["status"])]
245
+ if args.get("entry"):
246
+ cmd.extend(["--entry", str(args["entry"])])
247
+ return cmd
248
+
249
+ if tool_name == "handoff_record":
250
+ cmd = [
251
+ "handoff",
252
+ str(args["project"]),
253
+ "--agent",
254
+ str(args["agent"]),
255
+ "--status",
256
+ str(args["status"]),
257
+ "--done",
258
+ str(args["done"]),
259
+ ]
260
+ if args.get("evidence"):
261
+ cmd.extend(["--evidence", str(args["evidence"])])
262
+ if args.get("todo"):
263
+ cmd.extend(["--todo", str(args["todo"])])
264
+ return cmd
265
+
266
+ if tool_name == "workspace_commit":
267
+ return ["commit", "-m", str(args["message"])]
268
+
269
+ raise KeyError(f"Unknown tool: {tool_name}")
270
+
271
+
272
+ def _invoke_tool(tool_name: str, arguments: dict[str, Any]) -> tuple[str, bool]:
273
+ try:
274
+ cli_args = _build_cli_args(tool_name, arguments)
275
+ except KeyError as exc:
276
+ return f"Invalid arguments for {tool_name}: {exc}", True
277
+
278
+ env = dict(os.environ, PYTHONIOENCODING="utf-8")
279
+ ws_override = arguments.get("workspace_root")
280
+ if ws_override:
281
+ env["AGENT_WORKSPACE_ROOT"] = str(ws_override)
282
+
283
+ # Ensure package root is importable when executed directly from source tree.
284
+ pkg_parent = str(Path(__file__).resolve().parents[1])
285
+ existing_pp = env.get("PYTHONPATH", "")
286
+ if pkg_parent not in existing_pp.split(os.pathsep):
287
+ env["PYTHONPATH"] = f"{pkg_parent}{os.pathsep}{existing_pp}" if existing_pp else pkg_parent
288
+
289
+ proc = subprocess.run(
290
+ [sys.executable, "-m", CLI_MODULE, *cli_args],
291
+ capture_output=True,
292
+ text=True,
293
+ encoding="utf-8",
294
+ errors="replace",
295
+ env=env,
296
+ timeout=60,
297
+ )
298
+ combined = "\n".join(part for part in (proc.stdout.strip(), proc.stderr.strip()) if part).strip()
299
+ if not combined:
300
+ combined = "(no output)"
301
+ return combined, proc.returncode != 0
302
+
303
+
304
+ def handle_request(request: dict[str, Any]) -> dict[str, Any] | None:
305
+ method = request.get("method")
306
+ req_id = request.get("id")
307
+
308
+ # JSON-RPC notifications have no id and must not receive a response.
309
+ if method == "notifications/initialized" or (req_id is None and str(method).startswith("notifications/")):
310
+ return None
311
+
312
+ if method == "initialize":
313
+ client_ver = (request.get("params") or {}).get("protocolVersion") or PROTOCOL_VERSION
314
+ return {
315
+ "jsonrpc": "2.0",
316
+ "id": req_id,
317
+ "result": {
318
+ "protocolVersion": client_ver,
319
+ "capabilities": {"tools": {}},
320
+ "serverInfo": {
321
+ "name": "agent-shared-workspace",
322
+ "version": __version__,
323
+ },
324
+ },
325
+ }
326
+
327
+ if method == "ping":
328
+ return {"jsonrpc": "2.0", "id": req_id, "result": {}}
329
+
330
+ if method == "tools/list":
331
+ return {"jsonrpc": "2.0", "id": req_id, "result": {"tools": TOOLS}}
332
+
333
+ if method == "tools/call":
334
+ params = request.get("params") or {}
335
+ tool_name = params.get("name", "")
336
+ arguments = params.get("arguments") or {}
337
+ valid_names = {t["name"] for t in TOOLS}
338
+ if tool_name not in valid_names:
339
+ return {
340
+ "jsonrpc": "2.0",
341
+ "id": req_id,
342
+ "error": {"code": -32602, "message": f"Unknown tool: {tool_name}"},
343
+ }
344
+ text, is_error = _invoke_tool(tool_name, arguments)
345
+ return {
346
+ "jsonrpc": "2.0",
347
+ "id": req_id,
348
+ "result": {
349
+ "content": [{"type": "text", "text": text}],
350
+ "isError": is_error,
351
+ },
352
+ }
353
+
354
+ return {
355
+ "jsonrpc": "2.0",
356
+ "id": req_id,
357
+ "error": {"code": -32601, "message": f"Method not found: {method}"},
358
+ }
359
+
360
+
361
+ def main() -> None:
362
+ for raw_line in sys.stdin:
363
+ line = raw_line.strip()
364
+ if not line:
365
+ continue
366
+ try:
367
+ payload = json.loads(line)
368
+ except json.JSONDecodeError as exc:
369
+ err = {
370
+ "jsonrpc": "2.0",
371
+ "id": None,
372
+ "error": {"code": -32700, "message": f"Parse error: {exc}"},
373
+ }
374
+ sys.stdout.write(json.dumps(err, ensure_ascii=False) + "\n")
375
+ sys.stdout.flush()
376
+ continue
377
+
378
+ response = handle_request(payload)
379
+ if response is not None:
380
+ sys.stdout.write(json.dumps(response, ensure_ascii=False) + "\n")
381
+ sys.stdout.flush()
382
+
383
+
384
+ if __name__ == "__main__":
385
+ main()
@@ -0,0 +1,218 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-shared-workspace
3
+ Version: 0.1.0
4
+ Summary: Plain-text shared memory hub for multiple coding agents: Markdown SSOT + concurrency-safe CLI + zero-dependency MCP server.
5
+ Author: MAHONGHAO1
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/MAHONGHAO1/agent-shared-workspace
8
+ Project-URL: Repository, https://github.com/MAHONGHAO1/agent-shared-workspace
9
+ Project-URL: Issues, https://github.com/MAHONGHAO1/agent-shared-workspace/issues
10
+ Keywords: ai-agents,multi-agent,memory,mcp,cli,markdown,claude-code,codex
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Classifier: Topic :: Utilities
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Dynamic: license-file
24
+
25
+ # Agent Shared Workspace
26
+
27
+ [![Tests](https://github.com/MAHONGHAO1/agent-shared-workspace/actions/workflows/tests.yml/badge.svg)](https://github.com/MAHONGHAO1/agent-shared-workspace/actions/workflows/tests.yml)
28
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
29
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-stdlib%20only-brightgreen.svg)](#)
30
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
31
+
32
+ [中文](README.md) | **English**
33
+
34
+ **A dependency-free shared memory hub for multiple coding agents: plain-text Markdown SSOT + concurrency-safe CLI + Git versioning.**
35
+
36
+ ---
37
+
38
+ ## Why This Exists
39
+
40
+ If you run Codex, Claude Code, DeepSeek Harness, Antigravity, or other coding agents on the same codebase, each agent keeps its own isolated memory:
41
+
42
+ - Three agents hit the exact same bug three times.
43
+ - Yesterday's root-cause analysis disappears in today's session.
44
+ - Passing current project status between agents turns into repetitive copy-pasting.
45
+ - Vector-DB memory feels like a black box: hard to inspect, hard to edit, and easy to pollute silently.
46
+
47
+ This tool takes a simpler route: **shared memory lives in plain Markdown files inside a local workspace, every agent reads/writes through one stdlib-only CLI guarded by a cross-process file lock, and Git handles history and rollback.**
48
+
49
+ ## Architecture
50
+
51
+ ```mermaid
52
+ flowchart LR
53
+ subgraph Agents["Multiple Coding Agents (Thin Entry Pointers / Skill)"]
54
+ A1["Codex\n~/.codex/AGENTS.md"]
55
+ A2["Claude Code\n~/.claude/CLAUDE.md"]
56
+ A3["DeepSeek Harness\n~/.dsh/AGENTS.md"]
57
+ A4["Antigravity\n.agents/skills/"]
58
+ end
59
+
60
+ subgraph CLI["Unified Memory CLI (Python Stdlib Only)"]
61
+ TOOL["workspace_tool.py\ninit · exp · project · handoff · guard · commit"]
62
+ LOCK[".workspace.lock\nmsvcrt / fcntl exclusive lock"]
63
+ TOOL --- LOCK
64
+ end
65
+
66
+ subgraph SSOT["Plain-Text Single Source of Truth + Git"]
67
+ M1["AGENTS.md / NEW_PROJECT_SOP.md"]
68
+ M2["WORKSPACE.md"]
69
+ M3["EXPERIENCES.md"]
70
+ M4["Project_XXX/docs/当前状态与交接.md"]
71
+ GIT[("Local Git\nAuditable · Reversible")]
72
+ end
73
+
74
+ A1 & A2 & A3 & A4 --> TOOL
75
+ TOOL --> M1 & M2 & M3 & M4
76
+ M1 & M2 & M3 & M4 --> GIT
77
+ ```
78
+
79
+ ## Real CLI Output
80
+
81
+ ![Real CLI Demo](docs/assets/cli-demo.png)
82
+
83
+ ## One-Line Install (4 Distribution Channels)
84
+
85
+ ### 1. Agent Skill (`skills.sh` / Codex / Claude Code / Antigravity / Cursor)
86
+ ```bash
87
+ npx skills add MAHONGHAO1/agent-shared-workspace
88
+ ```
89
+ Ships with a self-contained stdlib `scripts/workspace_tool.py` inside the skill folder.
90
+
91
+ ### 2. Claude Code Plugin (Skill + MCP Server)
92
+ ```text
93
+ /plugin marketplace add MAHONGHAO1/agent-shared-workspace
94
+ /plugin install agent-shared-workspace
95
+ ```
96
+
97
+ ### 3. MCP Server (Zero Dependencies — Cursor / Claude Desktop / Antigravity)
98
+ ```json
99
+ {
100
+ "mcpServers": {
101
+ "agent-shared-workspace": {
102
+ "command": "python",
103
+ "args": ["-m", "agent_shared_workspace.mcp_server"],
104
+ "env": {
105
+ "PYTHONPATH": "/path/to/agent-shared-workspace/src",
106
+ "AGENT_WORKSPACE_ROOT": "/path/to/your-workspace"
107
+ }
108
+ }
109
+ }
110
+ }
111
+ ```
112
+ > Or install locally via `pip install .` to expose `agent-workspace` (CLI) and `agent-workspace-mcp` (MCP stdio server).
113
+
114
+ ### 4. DeepSeek Harness Plugin Bundle
115
+ Ready-to-publish DSH bundle lives in [`integrations/deepseek-harness/`](integrations/deepseek-harness/) (`dsh-agent-shared-workspace`, mounts the skill via `@deepseek-ai/dsh-skill-filesystem`).
116
+
117
+ ## Quick Start
118
+
119
+ Zero third-party packages required (Python 3.9+ stdlib only):
120
+
121
+ ```bash
122
+ # 1. Point to your workspace directory (defaults to cwd if unset)
123
+ export AGENT_WORKSPACE_ROOT=~/agent-workspace
124
+ # Windows PowerShell: $env:AGENT_WORKSPACE_ROOT="D:\agent-workspace"
125
+
126
+ # 2. Initialize skeleton files, workspace.config.json, .gitignore, and Git
127
+ python src/workspace_tool.py init --lang en
128
+
129
+ # 3. Create and register a project by SOP
130
+ python src/workspace_tool.py project new "ApiGateway" --owner codex
131
+
132
+ # 4. Record a tagged pitfall/experience
133
+ python src/workspace_tool.py exp add \
134
+ --title "Non-root container fails with EACCES on bind mount" \
135
+ --tag "docker,linux" \
136
+ --phenomenon "Container process gets Permission denied writing to mounted volume" \
137
+ --cause "Host directory is owned by root while container runs as uid 10001" \
138
+ --solution "Set user: in compose or chown in entrypoint" \
139
+ --criteria "Container successfully writes a 1 KB test file" \
140
+ --agent "claude-code"
141
+
142
+ # 5. Search by keyword and/or tag
143
+ python src/workspace_tool.py exp search --tag docker
144
+ python src/workspace_tool.py exp search "EACCES" --tag linux
145
+ python src/workspace_tool.py exp get EXP-001
146
+
147
+ # 6. Record a structured handoff (syncs handoff doc, project README, and board)
148
+ python src/workspace_tool.py handoff 001 --agent "codex" \
149
+ --status "Rate limiter verified" \
150
+ --done "Implemented token bucket and 12 unit tests" \
151
+ --evidence "tests/test_ratelimit.py 12/12" \
152
+ --todo "Canary rollout"
153
+
154
+ # 7. Check for uncommitted changes and commit
155
+ python src/workspace_tool.py guard
156
+ python src/workspace_tool.py commit -m "docs: initialize workspace and log EXP-001"
157
+ ```
158
+
159
+ ## Commands
160
+
161
+ | Command | Purpose |
162
+ | --- | --- |
163
+ | `init [--lang zh\|en] [--no-git]` | Idempotently scaffold docs, `workspace.config.json`, `.gitignore`, and Git |
164
+ | `status [--guard]` | Show active projects and Git status; `--guard` exits with code 1 if dirty |
165
+ | `guard` | Lightweight dirty-tree check (exit 0 when clean, exit 1 when dirty) |
166
+ | `exp search [query] [--tag t] [--list-tags]` | Search experiences by keyword/tag or list all tags with counts |
167
+ | `exp get EXP-001` | Inspect index metadata and full entry body (or sink path) |
168
+ | `exp add --title ... [--tag a,b] [--sink 001]` | Append a new experience with auto-incremented ID and index update |
169
+ | `exp update EXP-001 --note ...` | Append new evidence to an existing experience instead of duplicating |
170
+ | `project list` | List all `Project_XXX_*` directories and highest ID |
171
+ | `project new <name> --owner <agent>` | Create a project directory, README, handoff file, and register it |
172
+ | `project update <id> --status ...` | Sync status to both project README and workspace board |
173
+ | `handoff <id> --agent ... --status ... --done ...` | Append a handoff record and atomically update README and board |
174
+ | `commit -m <message>` | Stage and commit workspace changes (automatically excludes `.workspace.lock`) |
175
+
176
+ ## Built-in Safeguards
177
+
178
+ - **Cross-process Reentrant File Lock**: All write commands acquire `.workspace.lock` using `msvcrt.locking` on Windows and `fcntl.flock` on Linux/macOS. Concurrent agents serialize cleanly with zero ID collisions or torn Markdown. Timeout defaults to 10s (`AGENT_WORKSPACE_LOCK_TIMEOUT` to override).
179
+ - **Dirty-Tree Guard**: `guard` and `status --guard` return exit code `1` whenever uncommitted edits remain, suitable for shell hooks or end-of-session checks.
180
+ - **Configurable Filenames**: `init --lang en` writes `WORKSPACE.md` / `EXPERIENCES.md` / `NEW_PROJECT_SOP.md` and saves the mapping in `workspace.config.json`.
181
+
182
+ ## Wiring Into Your Agents
183
+
184
+ Copy the short snippets from [`examples/AGENTS-snippet.md`](examples/AGENTS-snippet.md) into each agent's native instruction file:
185
+
186
+ | Agent | Entry File |
187
+ | --- | --- |
188
+ | Codex | `~/.codex/AGENTS.md` |
189
+ | Claude Code | `~/.claude/CLAUDE.md` |
190
+ | DeepSeek Harness | `~/.dsh/AGENTS.md` |
191
+ | Antigravity | `<workspace>/.agents/skills/shared-workspace/SKILL.md` (see [`examples/SKILL.md`](examples/SKILL.md)) |
192
+
193
+ Keep agent entry files thin (commands & triggers only). Do not paste full workspace docs into every system prompt.
194
+
195
+ ## Why Not a Vector Database?
196
+
197
+ | Aspect | Vector RAG | This Approach |
198
+ | --- | --- | --- |
199
+ | Readability | Retrieved chunks, opaque ranking | Plain Markdown humans read and edit directly |
200
+ | Correctability | Requires re-embedding / re-indexing | Edit a paragraph or run `exp update` |
201
+ | Versioning | Separate snapshot tooling | Native Git diff, blame, and revert |
202
+ | Dependencies | Vector store + embedding service | Python stdlib only |
203
+ | Failure mode | Silently retrieves irrelevant memory | Explicit miss — visible and debuggable |
204
+
205
+ Trade-off: keyword, tag, and ID lookup only (no semantic similarity). Ideal for solo developers or small teams managing dozens to hundreds of verified lessons across multiple local agents.
206
+
207
+ ## Tests & CI
208
+
209
+ ```bash
210
+ python -m unittest discover -s tests -v
211
+ cd integrations/deepseek-harness && npm run check
212
+ ```
213
+
214
+ **15 Python end-to-end tests + 3 Node.js DSH bundle checks** run in isolated temp directories on both **Ubuntu** and **Windows** in GitHub Actions, including an **8-process concurrent write stress test**, **lock-timeout verification**, and a full **MCP stdio JSON-RPC lifecycle test**.
215
+
216
+ ## License
217
+
218
+ [MIT](LICENSE)
@@ -0,0 +1,9 @@
1
+ agent_shared_workspace/__init__.py,sha256=D0EN4LtdfIu8qEUEV14fPyfb3I7OxrOnDuv72J01NDs,103
2
+ agent_shared_workspace/cli.py,sha256=HvtLl3Y5M7B0iWm9_agWk10PYo3Ag4xDNr6b8RJ-KHk,42035
3
+ agent_shared_workspace/mcp_server.py,sha256=RW6P9TQj07CPG7WlyqF7etXwTgzDUT458SzrTxV6_Gs,15442
4
+ agent_shared_workspace-0.1.0.dist-info/licenses/LICENSE,sha256=ot7g40FAAFIS5bPlOw_YgMsaYrTgB6A3D57dbOyqxJw,1067
5
+ agent_shared_workspace-0.1.0.dist-info/METADATA,sha256=EuL-b-NL3QonQ8WpHWyPYtcvhI1r9VifK-XQwwIUetE,10134
6
+ agent_shared_workspace-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
7
+ agent_shared_workspace-0.1.0.dist-info/entry_points.txt,sha256=O9KZlBEsJ8boJDQyCFVKwWR3fmgacM1-ybLxZP3cOgg,129
8
+ agent_shared_workspace-0.1.0.dist-info/top_level.txt,sha256=QvoNAVKnO78A3z5UV97gbanJzoNJ3kBe0xII2CCtG90,23
9
+ agent_shared_workspace-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ agent-workspace = agent_shared_workspace.cli:main
3
+ agent-workspace-mcp = agent_shared_workspace.mcp_server:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MAHONGHAO1
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ agent_shared_workspace