Conversation
Split per-module Lua API docs into .agents/skills/bee-<module>/SKILL.md, with an index at .agents/bee-lua-api.md and a reference from AGENT.md.
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Several new Skill docs contain copy/paste-breaking example code and a few API return-value descriptions that don’t match the actual bindings, which should be corrected before merging.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 8
Open (8)
What changed in this PR
This PR adds agent-discoverable Skill documentation for the Lua-side bee.* modules, plus an index and references from AGENT.md, so AI tooling can quickly locate each module’s API, usage patterns, and cross-module conventions.
Changes:
- Added
.agents/bee-lua-api.mdas a central index (module → skill mapping) plus shared conventions and build/test notes. - Added per-module Skill docs under
.agents/skills/bee-<module>/SKILL.mdcovering API summaries and examples. - Updated
AGENT.mdto point contributors/agents to the new index and skills directory.
| File | Description |
|---|---|
| AGENT.md | Adds pointers to the new .agents API index and skills directory. |
| .agents/bee-lua-api.md | New index + cross-module conventions and test/build guidance. |
| .agents/skills/bee-async/SKILL.md | New Skill doc for async I/O API and usage patterns. |
| .agents/skills/bee-channel/SKILL.md | New Skill doc for channel-based thread communication. |
| .agents/skills/bee-crash/SKILL.md | New Skill doc for crash handler/dump behavior. |
| .agents/skills/bee-debugging/SKILL.md | New Skill doc for breakpoints/debugger detection. |
| .agents/skills/bee-epoll/SKILL.md | New Skill doc for epoll-style multiplexing. |
| .agents/skills/bee-filewatch/SKILL.md | New Skill doc for filesystem change notifications. |
| .agents/skills/bee-filesystem/SKILL.md | New Skill doc for paths/filesystem utilities. |
| .agents/skills/bee-platform/SKILL.md | New Skill doc for platform/compiler/arch info table. |
| .agents/skills/bee-select/SKILL.md | New Skill doc for select-style multiplexing. |
| .agents/skills/bee-serialization/SKILL.md | New Skill doc for cross-thread serialization rules. |
| .agents/skills/bee-socket/SKILL.md | New Skill doc for socket API, tri-state nonblocking conventions. |
| .agents/skills/bee-subprocess/SKILL.md | New Skill doc for spawning/managing subprocesses and pipes. |
| .agents/skills/bee-sys/SKILL.md | New Skill doc for exe/dll path, fullpath, and file locking. |
| .agents/skills/bee-thread/SKILL.md | New Skill doc for thread creation, lifecycle, and preload behavior. |
| .agents/skills/bee-time/SKILL.md | New Skill doc for wall/monotonic/thread CPU time. |
| .agents/skills/bee-windows/SKILL.md | New Skill doc for Windows-only helpers (encoding, console, SSD, handles). |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| ```lua | ||
| local async = require "bee.async" | ||
|
|
||
| local as <close> = assert(async.create([max_completions = 64])) -- <=0 报 "max_completions is less than or equal to zero." |
| 缓冲区： | ||
|
|
||
| ```lua | ||
| local wb = assert(async.writebuf([hwm = 65536])) |
| local chan = channel.create "test" | ||
| chan:push(1024); chan:push(1025) | ||
| assert(chan:pop() == 1024) | ||
| assert(chan:pop() == 1025) | ||
| local ok = chan:pop() -- false，通道已空 |
| ```lua | ||
| local debugging = require "bee.debugging" | ||
|
|
||
| debugging.breakpoint() -- 无条件断点（无调试器时会走平台默认的 trap/SIGTRAP 语义） |
| epfd:wait([timeout]) --> iterator | nil（已 close 时） | ||
| epfd:close() --> true | nil, err（重复 close 返回 nil） |
| end | ||
| ``` | ||
|
|
||
| 只要事件标志时可以直接累加（来自 `test_socket.lua` 的 `simple_select`）： |
| local newt = seri.unpack(seri.pack(t)) | ||
| assert(newt[i][j] == newt[j]) | ||
| ``` |
| local t1 = time.monotonic() | ||
| thread.sleep(1) | ||
| local t2 = time.monotonic() | ||
| assert(t2 - t1 >= 1) |
- async.create/writebuf: use positional arguments instead of invalid table syntax
|
@copilot 再review一下 |
Co-authored-by: sumneko <5213431+sumneko@users.noreply.github.com>
已处理并推送修正：e5dde55 |
|
一个模块一个skill也过于抽象了吧 |
|
各个模块的skill感觉关联不大，按需读取可以节省token嘛。合一起也行，你决定 |
|
分文件，AI自己就会按需加载。 |
|
意思是全放在 .agents/ 下，不套目录？ |
|
你可以看下 luamake 的 skill |
bee.lua is usually consumed as a 3rd party dependency, so the docs must not live in .agents/skills/ where agent clients would auto-load them from the host project.
|
看看这样行不。反正我从来不在意skill格式的，又不是我看。想了解就让AI当场总结给我 |
|
主要还是维护成本，luamake 的 skill 是让 AI 去看 bee 的 meta 文件。你看你这个 skill 是不是也可以改成这样。不然就要同时维护 meta 和 skill 了 |
|
luamake的问题是skill没有放在会被自动加载的地方，比如通过
对我们人类来说应该没有啥同时维护的成本 |
The meta/*.lua annotations are the authoritative API source and ship with the repo, so duplicating them in the skill docs only creates drift (this PR already had wrong signatures caught in review).
|
luamake 的 skill 不是给开发者用，而是使用者，skill 是安装到你的 AI 工具里，而非 luamake 的 agents.md。 针对 luamake 的 AI 开发者，会自己去看工程里的文件，给不给引用意义也不大。但这是另一个话题了，和这 issue 没关系。 这里你再 agents 里引用 skill，我持开放态度。但是我说的是 skill 里的内容和 meta 重复了，skill 只需要引用 meta，也能达到同样效果。重复代码增加维护和理解成本，这个准则无论是对人类还是 AI 都是适用的。 |
|
改过了你看看？ |
|
我评论之后，你没有提交过吧？ |
|
我在你评论前就按照你说的提交过了 |
|
引用 meta 之后，剩下的 skill 补充的内容，有存在的价值么。说实话我没精力去仔细审阅 AI 生成的这些信息，但看起来很多都无意义。 如果一个知识，AI 不知道，它生成的 skill 也不会知道。如果一个知识 AI 可以知道，那么 skill 的意义也不大。 skill 更多还是人类向AI传授知识用，如果纯 AI 生成的 skill 没经过人类的评审，还不如让AI 自己去理解。至少 AI 会随着时间的推移智力在增加，skill 你不持续维护就是固定的。 |
|
我先按照你的想法改一下吧，虽然我不认可。 |
|
你不给他 bee.lua 的代码只给他 skill，他就无法扫描 bee.lua 的实现和测试。如果只靠 meta 无法让 AI 或者人类理解如何使用 bee.lua，我觉得这是 meta 还不够完善，虽然我觉得大多数时候 AI 都能正确理解这些 api 的用法 |
做了什么
把 Lua 侧各
bee.*模块的 API 与用法整理成 agent 可发现的 skill 文档：.agents/bee-lua-api.md— 索引：模块 → skill 映射表、跨模块约定（三态返回值、<close>管理句柄、序列化类型限制）、构建/测试命令与 ltest 写法、可选链 patch 语义。.agents/skills/bee-<module>/SKILL.md— 16 个模块各一份，带 frontmatter（name+description）：platform、filesystem、socket、select、epoll、async、time、thread、channel、serialization、subprocess、filewatch、sys、crash、debugging、windows。每份包含 API 表、摘自test/的真实用法片段、以及注意事项/已知边界。AGENT.md— 增加对上述索引与skills/目录的引用。内容来源：
meta/*.lua（签名）+test/test_*.lua（行为契约与示例），纯文档改动，不含代码变更。验证
未触碰任何 C++/Lua 源码与构建脚本，
luamake -notest/luamake test行为不受影响。