前言¶
智能體寫代碼，最容易出的問題是「一口氣做完然後不知道該信什麼」。需求、實現、驗證、發佈、復盤這幾步如果不拆開，agent 往往在腦子裏把 spec 和 build 混在一起，check 就變成走過場。已有的做法裏，有的是給 agent 一堆結構化文檔模板，有的是靠人在流程節點上手動把關，但這些辦法要麼沒約束住 agent 的階段跳躍，要麼把負擔轉給了人。
下面介紹的 Galadon 走的是另一條路：它不試圖讓 agent 更聰明，而是把它限制在一個階段一個階段地走，每一步都留產物、設閘門。Galadon 由 Lumos-789 維護，也就是把現成的開源目錄頁上的插件拿來做對象，不誇大它的地位，只說明它能做什麼、怎麼用、有什麼限制。
這是什麼¶
一句話定位：Galadon 是一個面向 agent 構建項目的工程循環插件，把項目從 spec 到 learn 拆成五個階段，並提供腳手架和門禁。
它解決的問題是：當 agent 負責寫代碼、跑測試、發佈時，缺少一個穩定的階段邊界和產物檢查機制。Galadon 初始化一個小型工程工作區，讓 agent 一次只做一個階段，核心層只認三樣東西——階段（phases）、產物（artifacts）、閘門（gates）。其餘能力都通過 port 接口暴露，可以替換實現而不改五階段循環。
分類上它屬於「工作流」類。倉庫地址爲 https://github.com/Lumos-789/galadon ，目錄頁爲 https://www.skillhub.cn/plugins/Lumos-789/galadon 。
核心功能¶
五階段循環¶
Galadon 的主幹是一個固定順序的循環：
Spec -> Build -> Verify -> Ship -> Learn
這對應需求、實現、驗證、發佈、學習五個環節。agent 讀 galadon.yaml，執行當前階段，然後反覆跑 galadon check，直到循環推進到 learn。閘門的作用是讓不合格的產物直接失敗，而不是讓 agent 繼續往下糊。
Port 接口¶
Galadon 把「誰來幹」「用什麼骨架」「怎麼部署」這三件事抽成了三個 port：
| Port | 作用 | 內置參考實現 |
|---|---|---|
RolePort |
誰來幹活 | solo |
TemplatePort |
寫哪份 docs/profile.md；代碼骨架由 --layout/--stack 決定 |
web, api, static |
DeployPort |
怎麼構建、遷移、發佈、探測、回滾 | local, ssh |
內置實現只是例子。一個項目可以替換其中任意 port，而不必改動五階段循環本身。這也是它區別於「一個大模板包」的地方：流程是固定的，周邊能力是可插的。
Layouts 與 stacks¶
init --layout 會加上生產項目裏常見的項目內分層，默認的 none 保持基礎模板、不帶分層契約：
| Layout | 適用 | 生成內容（節選） |
|---|---|---|
none（默認） |
只想要裸循環 | 基礎模板 |
webapp |
有後端和前端的產品 | server/, src/, web/, e2e/, tests/, deploy/, openspec/, spec/, wiki/, .agents/, config.md |
service |
後端服務或定時任務 | server/, src/, tests/, scripts/, deploy/, openspec/, spec/, wiki/, .agents/, config.md |
plugin |
可分發的 agent 插件 | bin/<project>, src/<project>/, skills/<project>/, docs/, tests/, openspec/, spec/, wiki/, .agents/, config.md |
除 none 之外，每個 layout 在 spec/ 下都帶一層 spec 真值：INDEX.md（活動特性索引）、domains/README.md（每個 domain 一份行爲契約）、TESTING.md（變更到檢查的觸發矩陣）、CONSTITUTION.md（硬性規則）。這四個文件放在 templates/layouts/_shared/ 中，在某個 layout 自己的 common/ 層之前渲染，所以 layout 可以覆蓋某個文件，而 none 保持不變。
--stack 選擇代碼骨架和真實檢查命令：
| Stack | build | test |
|---|---|---|
python（默認） |
python3 -m compileall -f -q src server；plugin 佈局另跑 bash -n bin/<project> |
python3 -m unittest discover -s tests -v |
node |
node --check <layout entry>；plugin 佈局另跑 bash -n bin/<project> |
npm test（node --test tests/） |
none |
無 | 無 |
帶上 python 或 node stack 且 layout 非 none 時，初始化後至少有一個真實測試，galadon check 立刻是綠的；--stack none 沒有檢查命令，會明確報錯而非靜默通過。build 會對佈局裏每個源碼根做編譯或語法檢查，並對插件的 bash 包裝跑 bash -n，因此入口點損壞會直接讓閘門失敗。
gate 還會強制佈局契約：AGENTS.md、openspec/config.yaml、spec/INDEX.md、spec/domains/、spec/TESTING.md、spec/CONSTITUTION.md、三個 wiki/ 目錄、六個 .agents/ 槽位、非空 checks，以及 .gitignore 裏的 out/ 和 .agents/。缺哪一項，gate 會失敗並點名。倉庫裏模板中的 .agents/ 存儲爲 __agents__/，因爲倉庫自身忽略了 .agents/，渲染時再映射回來。
部署¶
遠程部署用 deploy.adapter: ssh，把目錄上傳到運行 systemd 和反向代理的主機，有 releases、原子化的 current/previous 切換、部署鎖，以及基於 commit 版本號的 JSON 探測：
deploy:
adapter: ssh
env: test
build: "mkdir -p dist && cp server.py dist/ && git rev-parse --short HEAD > dist/commit.txt"
probe_url: "https://demo.example.com/health.json"
probe_expect: "{{COMMIT}}"
artifact: "dist"
options:
host: 203.0.113.10
user: root
remote_root: /srv/demo
service: demo
domain: demo.example.com
listen: 127.0.0.1:18790
exec_start: "/usr/bin/python3 /srv/demo/current/server.py"
caddy_block: demo
bootstrap 創建系統用戶、release 目錄樹、systemd unit 和一塊帶標記的反向代理配置（它會先備份代理配置，校驗通過後才 reload）。teardown --yes 只刪除仍帶 bootstrap 標記的 root。
deploy.adapter: local 在 deploy.options.root（默認 .galadon/deploy）下使用同樣的 release 目錄樹：releases/<timestamp>-<version>、原子 current 切換、保留 previous、shared/deploy.lock。持有鎖時拒絕 ship；探測失敗會把 current 恢復回 previous，重新探測那一個 release，並以非零退出並點名實際生效的 release。
安裝與啓用¶
插件把 skill 和 CLI 一起發佈，不需要額外的安裝步驟。對 DeepSeek Harness，官方命令是（路徑或倉庫佔位符需填實際值）：
dsh plugin --profile headless add <path-or-repo>
對另外兩個宿主，分別是：
zcode plugins install galadon@<marketplace>
codex plugin add galadon@<marketplace>
工作區內 agent 會調用自帶的 bin/galadon。如果要自己用 CLI，可以直接調插件目錄裏的 bin/galadon，或者安裝它：
pip install <plugin-dir> # or: pipx install <plugin-dir>
依賴 Python 3.10+ 和 PyYAML。這些命令均來自插件 README 原文，安裝時請把 <path-or-repo>、<marketplace>、<plugin-dir> 替換成實際路徑或倉庫名，不要憑名稱自行拼接 github:owner/repo。
典型用法¶
初始化一個目錄，再讓 agent 推進循環：
galadon init --template api --role solo # 空目錄；已有文件時用 --force
galadon next # 一次只給一個階段的下一個動作
然後交給 agent：它讀 galadon.yaml，做當前階段，並反覆跑 galadon check，直到循環到達 learn。默認 none layout 下第一個閘門是 spec：init 會寫出一個滿是 TODO 的 spec/spec.md 樁，於是 check 會報 “spec/spec.md still contains TODO”，直到你把它寫完。init 也故意讓 checks.build 和 checks.test 爲空，所以 spec 完成後 check 會明確報 “no checks configured — declare checks.build/checks.test”，直到你聲明真實命令。
常用完整命令：
galadon init --template web --role solo
galadon init --layout webapp --stack python --template web
galadon next
galadon check
galadon new
galadon bootstrap --env test
galadon ship --env test
galadon teardown --env test --yes
galadon init --list-layouts 會輸出 stable text，列出可用 layouts 和 stacks。
ship 在沒有真實探測的情況下不會報告成功；生產環境發佈需要在當前會話里加 --yes-prod。
適用場景與注意¶
適合的場景：想讓 agent 在一個工程裏按固定階段推進，同時要求每一步都有可檢查的產物和閘門的項目。如果需要的是外部發布流程、CI 編排或團隊協作權限體系，Galadon 只提供基礎循環和兩類 deploy adapter，覆蓋不了這些。
運行時權限要注意：插件以當前 DSH 進程的權限運行。安裝前應自行檢查源碼與許可證——其許可證信息以倉庫和插件元數據爲準，本次資料中 package.json 記爲 MIT，倉庫地址爲 https://github.com/Lumos-789/galadon 。
安裝命令不要憑插件名稱自行拼接，優先使用 README 給出的命令和佔位符。另外 bootstrap/ship 會在遠程主機上寫文件、重啓服務，teardown --yes 會刪目錄，指向重要機器之前應先讀一遍 README 的 Side effects 一節。
結尾¶
Galadon 的價值不在於它帶了多少模板，而在於它把 agent 項目最缺的階段邊界和閘門固定了下來，其餘能力留給 port 替換。目錄頁：https://www.skillhub.cn/plugins/Lumos-789/galadon ，倉庫：https://github.com/Lumos-789/galadon 。
