{"_id":"@tingyen/agent-cockpit","_rev":"2-8594d6757f495968bc525bfdb353e2ed","name":"@tingyen/agent-cockpit","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.0-stage":{"name":"@tingyen/agent-cockpit","version":"0.0.0-stage","_id":"@tingyen/agent-cockpit@0.0.0-stage","stub":true,"maintainers":[{"name":"tingyen","email":"alexchu1227@gmail.com"}],"dist":{"shasum":"96075abd1ce4ee34077f5a430184393b02903500","tarball":"https://registry.npmjs.org/@tingyen/agent-cockpit/-/agent-cockpit-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-bTvhhQqdfwdJ9m91Lz9GVBsnAWbtKkI7D1c2KVkwbwCj3yONsfNOylWsKk9oII38uHDQTJpqmDga6LXUo3IchA==","signatures":[{"sig":"MEUCIQC0DYznmBWqQrXvWmn8bRAFdBLJD/EM57FFO9VDgwztmgIgbLQUOIrvNbpsOGZQGVxoChFKUwtJzLt7IiSpBDnRwk0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":344},"_npmUser":{"name":"tingyen","email":"alexchu1227@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.0":{"_id":"@tingyen/agent-cockpit@0.1.0","bin":{"cockpit":"bin/cockpit.mjs"},"bugs":{"url":"https://github.com/chutingyean/Agent-Cockpit/issues"},"dist":{"shasum":"d0042800cd5956686b80353758aff78328a4c5f5","tarball":"https://registry.npmjs.org/@tingyen/agent-cockpit/-/agent-cockpit-0.1.0.tgz","fileCount":41,"integrity":"sha512-aKjZaAkgZYPtyPq0/cKlkhl9YN99swCUJVQV3EScDetzrY+gEuMQWI3DOvI94UO9pyFmRpYipOG/Rfmlu/78ag==","signatures":[{"sig":"MEUCIQCsx2VlBGJwC2we0b7wcykiSTADE55kZAarWHOXbIrPxwIgOCNDrehvVA7qkeas38PSZkK5c2hEAh+Ka0L55Y/r1Tk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICF48namV7OQKMjJ0zEHO6O/xKoe4lxHZpKqv/yapXEKAiEA6MKOCfaUa12dd7xkf5L6H60+g9IaYrLpw+DbXCzU+iA="}],"unpackedSize":1259201},"name":"@tingyen/agent-cockpit","type":"module","author":{"name":"chutingyean"},"engines":{"node":">=22.13"},"gitHead":"a968c6bc2568a5036981f896939234aaac29c1cd","license":"AGPL-3.0-or-later","mcpName":"io.github.chutingyean/agent-cockpit","scripts":{"demo":"node bin/cockpit.mjs demo","test":"node --test test/*.test.mjs"},"version":"0.1.0","_npmUser":{"name":"tingyen","email":"alexchu1227@gmail.com"},"homepage":"https://github.com/chutingyean/Agent-Cockpit#readme","keywords":["mcp","model-context-protocol","ai-agents","research","reproducibility","claude-code","codex","evidence","provenance"],"repository":{"url":"git+https://github.com/chutingyean/Agent-Cockpit.git","type":"git"},"_npmVersion":"11.13.0","description":"An evidence-chain whiteboard and MCP server that keeps AI research agents honest: every claim traces back to the run and the code that produced it.","directories":{},"maintainers":[{"name":"tingyen","email":"alexchu1227@gmail.com"}],"_nodeVersion":"24.16.0","dependencies":{"zod":"^4.6.7","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-cockpit_0.1.0_1793948412064_0.8932058699774074"}}},"time":{"created":"2026-11-06T06:58:55.150Z","modified":"2026-11-06T07:00:12.503Z","0.0.0-stage":"2026-11-06T06:58:55.150Z","0.1.0":"2026-11-06T07:00:12.243Z"},"description":"An evidence-chain whiteboard and MCP server that keeps AI research agents honest: every claim traces back to the run and the code that produced it.","maintainers":[{"name":"tingyen","email":"alexchu1227@gmail.com"}],"readme":"<p align=\"center\"><img src=\"docs/assets/banner.png\" alt=\"Agent Cockpit：讓每一個研究結論都能追到產生它的程式碼\" width=\"100%\"></p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/chutingyean/Agent-Cockpit/actions/workflows/test.yml\"><img src=\"https://github.com/chutingyean/Agent-Cockpit/actions/workflows/test.yml/badge.svg\" alt=\"tests\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-AGPL--3.0--or--later-blue\" alt=\"license: AGPL-3.0-or-later\"></a>\n  <img src=\"https://img.shields.io/badge/node-%E2%89%A522.13-339933\" alt=\"node >= 22.13\">\n  <img src=\"https://img.shields.io/badge/MCP-any%20agent-7c4dcc\" alt=\"MCP: any agent\">\n</p>\n\n<p align=\"center\"><a href=\"README.md\">English</a> · <b>繁體中文</b></p>\n\n**Agent Cockpit** 是給做研究的 AI agent 用的本機白板加上 MCP server。任何支援 MCP 的 agent（Claude Code、Codex、Cursor、Gemini CLI…）都把工作畫到同一張白板上：研究路徑、任務、每一次實驗、每一個結論，以及每次實驗用到的程式碼。一個確定性引擎持續檢查整條證據鏈，任何一環被改，依賴它的卡片立刻變紅。不必讀程式碼，看白板就知道哪些結果還能信、為什麼。\n\n<p align=\"center\"><img src=\"docs/assets/replay.gif\" alt=\"重播一次真實的工作過程：兩個 agent 完成研究、沒回報的改動讓一個結論失效、人裁決、agent 還原\" width=\"100%\"></p>\n<p align=\"center\"><sub>重播一次真實的工作過程：Claude Code 和 Codex 從空專案做完一個小研究。有人偷改了程式、沒有回報，一個結論失效，駕駛艙自動送出裁決並產生簡報；人選了「還原」，agent 照做。</sub></p>\n\n## 為什麼需要它\n\n用 AI agent 做研究幾天之後，同樣的問題會一再發生：\n\n- **結論的地基偷偷移動**：agent 改了評分器、資料處理或統計方法，之前「已驗證」的數字其實不再成立，但沒有人發現。\n- **對不上帳**：檔案被改了卻沒有 agent 說，或說改了卻沒改。\n- **裁決積壓、前提硬化、原地打轉**：該人決定的事堆著沒人回，沒驗證過的推論被當成地基，agent 一直換超參數「再試一次」。\n- **程式長得比你讀得快。**\n\nAgent Cockpit 把這些變成機器檢查得了的規則，結果畫在同一張白板上。\n\n## 功能\n\n- **證據鏈細到 JSON 欄位**：結論必須引用某次實驗真的寫出的數值。每次執行都記下腳本、它依賴的每個檔案、以及它碰得到的每個函式的雜湊。任何一個變了，那次執行就過期，建立在它上面的結論標成「待重驗」；改回原樣，雜湊對上就自動恢復。\n- **任何 MCP agent 都能接**：agent 身分從 MCP 握手取得。`cockpit init` 寫好 Claude Code、Cursor、VS Code、Gemini CLI 的設定，並印出 Codex 的指令。\n- **只有一個寫入咽喉**：MCP、命令列、白板上的操作全部經過同一個驗證函式；不合規的寫入會被拒收，並告訴 agent 怎麼改。被拒收的也會留紀錄。\n- **抓得到沒回報的改動**：不管 agent 有沒有回報，真實的檔案變更都會被偵測到。沒回報的變更會擋下 `git commit`，Claude Code 也要先回報才能結束回合。\n- **內建程式碼圖與審查，不必另外安裝**：輕量版的 graphify 呼叫圖提供依賴閉包、社群、核心節點與影響範圍；規則審查在每次檔案變更時自動看改到的行。裝了真的 [graphify](https://github.com/Graphify-Labs/graphify) 或 [open-code-review](https://github.com/alibaba/open-code-review) 會自動改用。\n- **人在迴圈裡裁決**：agent 用 `cockpit_decide` 發問並等待。改動讓結論失效時，駕駛艙會自己送出裁決，並產生一頁證據簡報（由 [answer-me-with-html](https://github.com/QingYunA/answer-me-with-html) 排版）。\n- **重播**：所有東西都是只追加的事件，白板可以拖回或播放到任何一刻；問題修好之後，當時的簡報仍找得回來。\n- **本機、確定性**：白板只綁 127.0.0.1；所有檢查都是規則，不呼叫 LLM，0 token。\n\n## 快速開始\n\n需要 Node.js 22.13 以上（用到內建的 `node:sqlite`）、git；示範專案需要 python3。\n\n```bash\ngit clone https://github.com/chutingyean/Agent-Cockpit.git\ncd Agent-Cockpit\nnpm install\nnpm run demo                                       # 產生示範研究專案：真的跑 6 次實驗、登記 6 個結論\nnode bin/cockpit.mjs serve --repo demo/research    # 打開 http://127.0.0.1:4180\n```\n\n另開一個終端機，弄壞一個地方看白板怎麼反應：\n\n```bash\nnode bin/cockpit.mjs demo --break      # 偷偷把評分器的答案比對改鬆，不回報\nnode bin/cockpit.mjs demo --restore    # 改回來：雜湊對上，結論恢復\n```\n\n<p align=\"center\"><img src=\"docs/screenshots/2-board-broken-chain.png\" alt=\"評分器被改之後：依賴它的結論變紅，駕駛艙送出裁決\" width=\"100%\"></p>\n\n## 用在自己的研究專案\n\n不需要 clone：\n\n```bash\ncd /path/to/your-research                                   # 必須是 git repo\nnpx -y @tingyen/agent-cockpit init                      # MCP 設定、AGENTS.md、Stop hook、pre-commit\nnpx -y @tingyen/agent-cockpit serve                     # 白板\nnpx -y @tingyen/agent-cockpit run -- python3 train.py   # 實驗一律透過 cockpit 跑\n```\n\n想要固定的 `cockpit` 指令：`npm install -g @tingyen/agent-cockpit`。\n\n`init` 只會寫在你的專案資料夾裡。用 agent 打開專案，它就會讀到 `AGENTS.md` 和 MCP 設定。各家 agent 的接法見[教學](docs/tutorial.zh-TW.md)。\n\n**Claude Code plugin**：加上一個技能，教 Claude 什麼時候、怎麼用 Agent Cockpit（包括怎麼設定）：\n\n```bash\nclaude plugin marketplace add chutingyean/Agent-Cockpit\nclaude plugin install agent-cockpit@agent-cockpit\n```\n\n同一份技能在 [`skills/agent-cockpit/SKILL.md`](skills/agent-cockpit/SKILL.md)，其他會讀 `SKILL.md` 的 agent 也能用。MCP server 也登記在 [MCP Registry](https://registry.modelcontextprotocol.io)，名稱是 `io.github.chutingyean/agent-cockpit`。\n\n## 運作方式\n\n<p align=\"center\"><img src=\"docs/figures/evidence-graph.png\" alt=\"證據圖：結論 → 執行 → 程式碼 → 架構分層，審查、摘要與簡報是註記\" width=\"100%\"></p>\n\n- **看內容雜湊，不看時間戳記**：過期與否靠比對雜湊，所以把檔案改回去就會精確地恢復。\n- **函式層級**：Python 依賴檔裡，只改到這次執行碰不到的函式不算過期；改到碰得到的函式、import 或模組層程式碼一律算。\n- **事件溯源**：`.cockpit/events.jsonl` 是唯一的真相，同時就是 agent 的工作紀錄（請 commit 它）。白板是純函式的投影（`reduce` → `derive`），所以能重播。\n\n<p align=\"center\"><img src=\"docs/figures/architecture.png\" alt=\"架構：agent、命令列、白板都經過同一個咽喉寫進只追加的事件庫，引擎把它投影到白板\" width=\"100%\"></p>\n\n## MCP 工具\n\n| 研究工具 | 用途 |\n|---|---|\n| `cockpit_overview` | 開工先呼叫：要人決定的事、待重驗的結論與原因、沒回報的變更 |\n| `cockpit_plan`／`cockpit_stage` | 研究路徑；階段的必要工具沒呼叫過不能結束 |\n| `cockpit_task` | agent 自己的任務卡，每一輪更新（做了什麼、為什麼、下一步） |\n| `cockpit_run` | 執行實驗並記錄 |\n| `cockpit_claim` | 登記結論；證據必須是某次執行寫出的檔案與欄位 |\n| `cockpit_hypothesis`／`cockpit_premise` | 假設與還沒驗證的前提 |\n| `cockpit_decide`／`cockpit_decisions` | 請人裁決、取回裁決 |\n| `cockpit_report` | 回報改了哪些檔案 |\n| `cockpit_review` | 程式碼審查：有 ocr 跑 ocr，沒有用內建規則；也可以回報自己的審查結果 |\n\n畫布工具：`canvas_list`、`canvas_read`、`canvas_search`、`canvas_createNode`、`canvas_link`、`canvas_diagram`（[md²](https://github.com/jan-bogaerts/md2) 格式的架構圖）、`canvas_structure`（程式碼圖與影響範圍）。\n\n## 命令列\n\n`npm install -g @tingyen/agent-cockpit` 之後就有全域的 `cockpit` 指令；否則用 `npx -y @tingyen/agent-cockpit <指令>`，或在 clone 下來的資料夾用 `node bin/cockpit.mjs`。\n\n| 指令 | 用途 |\n|---|---|\n| `cockpit init` | 寫好 MCP 設定、規則檔、Stop hook 與 pre-commit |\n| `cockpit serve [--port 4180]` | 開白板 |\n| `cockpit run -- <命令>` | 執行並記錄實驗 |\n| `cockpit graph` | 重建程式碼圖（有 graphify 用 graphify） |\n| `cockpit review [--all]` | 程式碼審查（有 ocr 用 ocr；預設只看改到的行） |\n| `cockpit status`／`cockpit check` | 印出駕駛艙摘要／列出沒回報的變更 |\n| `cockpit demo [--break\\|--restore\\|--fresh]` | 示範專案 |\n\n所有指令都可以加 `--repo <路徑>`，預設是目前資料夾。\n\n## 專案結構\n\n```\nbin/cockpit.mjs      命令列\nsrc/engine.mjs       reduce 與 derive：證據鏈、傳播規則、導覽、簡報草稿\nsrc/gate.mjs         寫入咽喉\nsrc/store.mjs        事件庫（node:sqlite）與畫布投影\nsrc/run.mjs          cockpit run\nsrc/graph.mjs        內建程式碼圖（輸出與 graphify 相容）\nsrc/review.mjs       內建規則審查\nsrc/mcp.mjs          MCP server\nsrc/server.mjs       白板 server（SSE、裁決、簡報、重播）\nweb/board.html       白板（不用框架、不用打包）\ndemo/template/       示範研究專案（Python，可真的跑）\nskills/              教 agent 在 Agent Cockpit 底下工作的 SKILL.md\n.claude-plugin/      Claude Code plugin 與 marketplace 設定\nserver.json          MCP Registry 的登記資料\ndocs/                教學、圖、截圖、一次真實工作過程的紀錄\ntest/                node:test（npm test）\n```\n\n## 文件\n\n- [教學](docs/tutorial.zh-TW.md)：從示範專案到自己的專案、各家 agent 的接法、重播，以及一次真實工作過程的紀錄\n- [真實工作紀錄](docs/live-run/)：事件、agent 寫的程式、agent 的輸出\n\n## 致謝\n\nAgent Cockpit 把六個專案的想法融合成同一張證據圖：\n[research-cockpit](https://github.com/sanngotall/research-cockpit)（結論、假設、前提、裁決）、\n[graphify](https://github.com/Graphify-Labs/graphify)（程式碼圖）、\n[open-code-review](https://github.com/alibaba/open-code-review)（程式碼審查）、\n[Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)（白話摘要、分層、導覽、讀者模式）、\n[md²](https://github.com/jan-bogaerts/md2)（架構圖格式）、\n[answer-me-with-html](https://github.com/QingYunA/answer-me-with-html)（一頁簡報）。\n哪些東西附在 repo 裡、各是什麼授權，見 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。\n\n## 授權\n\nCopyright (C) 2026 chutingyean\n\nAgent Cockpit 是自由軟體：你可以依照自由軟體基金會發布的 [GNU Affero 通用公共授權條款](LICENSE)第 3 版，或（依你的選擇）任何更新的版本，重新散布或修改它。如果你修改後透過網路讓別人使用，必須提供你那個版本的原始碼。第三方元件維持各自的授權，見 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。\n","readmeFilename":"README.zh-TW.md","homepage":"https://github.com/chutingyean/Agent-Cockpit#readme","keywords":["mcp","model-context-protocol","ai-agents","research","reproducibility","claude-code","codex","evidence","provenance"],"repository":{"url":"git+https://github.com/chutingyean/Agent-Cockpit.git","type":"git"},"author":{"name":"chutingyean"},"bugs":{"url":"https://github.com/chutingyean/Agent-Cockpit/issues"},"license":"AGPL-3.0-or-later"}