spike(framework): define the Freebuff support contract
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 42/100
- Issue 类型
- 功能
- 描述清晰度
- 基本清楚
- 活跃度
- 活跃
- 技术栈
- typescript
调研方向
Start with cli/src/kernel/tool.ts and the five reference tables: detection.md, tools.md, tool-detect.md, sync-arguments.md, plus plugins/aidd-context/hooks/update_memory.js. Then inspect the existing OpenCode and Kilo profiles and bridges, and verify whether Freebuff has a usable session-start hook surface. Done means Freebuff detection, AGENTS.md wiring, profile delivery, and maintenance behavior are consistently represented and validated.
由索引模型根据 Issue 内容生成。
描述
Problem to solve
aidd-context has no representation for Freebuff. It is absent from all five places that enumerate
AI tools, including TOOL_FILES in
update_memory.js. A project that is worked on with
Freebuff therefore cannot keep its AIDD memory current.
On a real project that runs AIDD, with the copy of the hook installed in that project (byte-identical
to upstream/next):
$ node .opencode/hooks/aidd-context/update_memory.js opencode
# exit 0, memory block updated
$ node .opencode/hooks/aidd-context/update_memory.js freebuff
update_memory: unknown tool freebuff (known: claude, codex, cursor, opencode, copilot)
# exit 1, refused
$ node .opencode/hooks/aidd-context/update_memory.js kilo
update_memory: unknown tool kilo (known: claude, codex, cursor, opencode, copilot)
# exit 1, refused
The effect is not cosmetic. Writing a new memory file and syncing:
| synced for | exit | block lists the new file |
|---|---|---|
opencode |
0 | yes |
freebuff |
1 | no |
kilo |
1 | no |
The guard is doing its job — the tool is simply not in the list.
This is not a Freebuff-shaped gap. Kilo is in the same position today: AiToolId in
cli/src/kernel/tool.ts carries six values including kilo, and 12 files under cli/src/ know
the tool, yet kilo appears zero times in plugins/ and update_memory.js kilo exits 1. Two
tools, one cause: the wiring table and the plugin reference tables are maintained separately from
the tool registry, and nothing checks that they agree.
Proposed solution
Add Freebuff as a detected tool wired to AGENTS.md, alongside codex, cursor and opencode.
- Detection signal:
.freebuff/, a project-scoped directory holdingproject-id. It is created
when a project is opened in Freebuff, so it is behavioural rather than inferred — I watched it
appear when I started a session. The vendor writes it fromsetProjectRootin
cli/src/project-files.tswitheveryRepository: IS_FREEBUFF, so it is written in every Git
project, not only in ones without a hosted remote; I confirmed it present in a repo that does
have a GitHub remote. - Wiring target:
AGENTS.md. Freebuff reads projectAGENTS.mdandCLAUDE.md. The vendor
quick-start says "New projects — if you don't already have an AGENTS.md or CLAUDE.md (Codebuff
will also read these files)" — and that page is the right evidence here, because Freebuff is the
same CLI built withFREEBUFF_MODE=true, while the knowledge-file resolution lives in
common/src/constants/knowledge.tsandsdk/src/run-state.ts, neither of which is gated on that
flag. PickingAGENTS.mdalso matches how #914 settled the same question for Kilo. - No new surface:
AGENTS.mdis already the target for three tools, so the existing "tools
sharing a context file wire it once" rule intools.mdcovers this.
Wiring is four table edits (detection.md, tools.md, tool-detect.md, sync-arguments.md) plus
the TOOL_FILES entry. That is necessary and not sufficient — see below.
Content type
- Other
Target tool(s)
- Other — Freebuff, which the dropdowns do not list.
Additional context
-
The five tables are the ones that disagree with each other, and the
sync-arguments.mddefault
is where a fourth writer shows up. Its rule reads "Otherwise derive args from synced context
files;AGENTS.mddefaults tocodex". A third tool already targetsAGENTS.md, so that
default is already arbitrary; a fourth makes it arbitrary in a way a reader will hit. Worth
settling as part of this, not after. -
Wiring is half of it, and the half I cannot deliver is the half that matters.
TOOL_FILESis
the wiring table; it does not maintain anything. Maintenance runs per tool through the CLI
profiles, and all six existing profiles declareacceptsHooks: true— so a tool is not
automatically maintained, and a new one needs its profile wired deliberately:tool hook delivery mechanism claude yes native plugin, pluginRootToken=CLAUDE_PLUGIN_ROOTcopilot yes native plugin, .github/plugins/codex yes writes a hook entry to .codex/config.tomlcursor yes hooksContentFormat: "flat", routed to.cursor/hooks.jsonopencode yes generated bridge ( opencode-hooks-bridge.ts)kilo yes generated bridge ( kilo-hooks-bridge.ts)freebuff no profile — The distinction that matters is
mode: "flat"versus native. Claude, Copilot and Cursor take
hooks.jsonmore or less as-is. OpenCode and Kilo cannot express it natively, so the CLI
generates a bridge module that parseshooks.jsonand replays theSessionStartcommands.
Freebuff would need a profile and one of those two shapes decided for it — which is a question
for whoever validates this, not a guess I should make in a PR. I could not find a session-start
hook surface in the vendor's published source: there is nohooks.jsonconcept, and
SessionStartappears nowhere. The one hook concept that does exist isrun_file_change_hooks,
and its SDK path is an explicit no-op ("File change hooks are not supported in the SDK
environment") — so I cannot claim a bridge is generatable. -
I checked the vendor's source rather than assuming, and its docs disagree with its own code.
Freebuff resolves one knowledge file per directory, first match wins
(selectHighestPriorityKnowledgeFileinsdk/src/run-state.ts, walking
KNOWLEDGE_FILE_NAMES_LOWERCASEover that directory's candidates). That list is
['AGENTS.md', 'CLAUDE.md'](common/src/constants/knowledge.ts);knowledge.mdis no longer a
knowledge file, andisKnowledgeFileadditionally accepts*.knowledge.md. Two comments in
run-state.tsstill describe the oldknowledge.md-first ordering while the code below them no
longer implements it, and the vendor's publisheddocs/tips/knowledge-filesstill tells users
~/.knowledge.mdis "highest priority" — a fileloadUserKnowledgeFilesno longer matches at
all. So the code is right and the docs are stale here.AGENTS.mdis therefore the correct
target, and a project that also carries aknowledge.mdis not a special case. I am reporting
this only as the reason my choice is grounded; the doc fix is theirs to make. -
I have not checked Discussions, only issues. Searched for
freebuffandcodebuffacross
open and closed issues: no hit, so I do not believe this is tracked yet. -
Sequencing with #914 is a judgement call for the maintainers, not mine.
-
I am not asking for a PR to be opened pre-emptively. Per
CONTRIBUTING.mdan issue is validated
first — a Certified Member or Maintainer moves it toTodo— and after that anyone may pick it up,
including me.
Code of Conduct
- I agree to follow this project's Code of Conduct.
- 主要语言
- TypeScript
- 星标
- 481
- 派生
- 45
- 平均合并
- 1 天 13 小时
- 30 天内合并 PR
- 91
环境准备
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
ai-driven-dev/framework 的其他 Issue
-
难度 2/5 1-3 小时 新手友好度 86/100
ai-driven-dev/framework#1311 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 79/100
ai-driven-dev/framework#1244 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
ai-driven-dev/framework#1197 ·
维护者通常 1 天内回复
-
refactor(aidd-context): apply the new skill template to learn可能已有人在做 @blafourcade 于 3 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 72/100
ai-driven-dev/framework#1186 · 已指派 1 人 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 83/100
ai-driven-dev/framework#1163 · 1 条评论 ·
维护者通常 1 天内回复
查看 ai-driven-dev/framework 的全部 Issue
相似的 Issue
-
db-d1-sqlite: upsert is aliased to updateOne, so payload.kv.set never inserts new keys可能已有人在做 @pcbeingused333 今天认领。 未关闭Bug db: d1-sqlite Payload OSS
难度 2/5 1-3 小时 新手友好度 76/100
payloadcms/payload#19766 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 68/100
device-management-toolkit/sample-web-ui#3711 ·
维护者通常 1 天内回复
-
bug impact:low Team: SecuritySolution Team:Defend Workflows v9.6.0
难度 2/5 1-3 小时 新手友好度 72/100
elastic/kibana#306401 · 3 条评论 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 68/100
agentes-chat/agentes-chat#927 ·
维护者通常 1 天内回复
-
Closing a pinned tab jumps to the Tabs section instead of the next open pinned tab可能已有人在做 @seenimohamed 今天认领。 未关闭bug
难度 2/5 1-3 小时 新手友好度 78/100
ardia-browser/ardia#2769 ·
维护者通常 1 天内回复