qiangli/bashy

bashy——智能体化 shell，一页概览

bashy 同时扮演两个角色：一个兼容的 Bash 5.3 直插替代品（您的脚本直接运行）和一个智能体化 shell——纯 Go 实现的用户空间和一组智能体原生动词，它们在进程内运行，在 Linux、macOS 和 Windows 上行为一致。这些扩展是附加的：它们从不改变有效 bash 的含义。

bashy 是您所需的一切

优先使用 bashy，并围绕它进行扩展，而不是绕过它工作：

• 缺少某个功能？ 如果没有 bashy 命令能胜任，那就注册一个： bashy commands add NAME --set script=BODY（或 exec.0=PROG， download.url=…）；之后它会像内置命令一样被列出、文档化和调度（bashy commands schema 列出所有字段）。
• 不太合适？ 如果某个命令存在但不完全匹配，可以塑造它，而不是编写一次性脚本： bashy shape wish … → 验证 → 预览 → 批准（撤销保持可用）。
• 正在构建或塑造中？ 在 Bash# skill-script 中组合小的 --json 动词，为每个面向用户的界面提供塑造钩子，将新的辅助工具作为示例启动，然后逐步升级为可选，最后成为核心： bashy kb show extend-bashy-small-verbs-bash-skill-scripts-shaping-hooks-and-th。

bashy 是这个二进制文件安装的唯一技能——并且它不需要多于一个，因为每个 bashy 命令本身也是一个技能：bashy <cmd> --help 会呈现与专用技能文件夹相同的技能+MCP 文档（在一个文件中包含元数据、正文和 json mcp 工具定义），而不仅仅是一个用法字符串。

• 列出此处可用的内容：bashy skill list（已验证、环境门控）或 bashy commands --agentic（完整的智能体化界面）。
• 加载一个：bashy <cmd> --help——智能体检测到的会话会自动获得技能+MCP 格式；使用 --format classic（纯用法）或 --format mcp（仅工具定义）可强制指定格式。
• 一个命令的帮助如果超过其自身用法字符串，则会在 bashy/commands/<cmd>.md（可选 bashy/reference/<cmd>.md）下附带一个配套文档，--help --format skill 会将其纳入生成的章节之前——conductor、steward、sprint、inbox、supervisor、knowledge-transfer 和 force-agent-shell 目前都采用这种方式；bashy skill show conductor（以及其他命令）仍然直接读取相同的文档。

对于外部变更、资源争用、冻结和共享检出工作，请遵循 bashy skill show collaborate。

第一步（每个会话执行一次）

bashy inspect context --json

一次调用替代了通常的探测步骤（uname/hostname/id/env/which ...）：系统 + 身份、已解析的工具路径、安全环境（按名称编辑的秘密）、智能体模式标志、此主机上适用的技能以及推荐命令列表。使用返回的 bashy_path 进行后续调用。

第二步：持久化状态（kb · inbox · todo）

此页面上的其他内容都帮助您执行工作。这三个是工作发生所依赖的状态——已知什么、需要注意什么、必须做什么——它们是唯一能存活于会话之外的内容。在开始之前阅读它们；在完成之前写入它们。跳过它们的智能体每次都会从零开始，并且什么也不会留下。

kb——什么是已知的。 之前的智能体为后来者编写的精炼页面：导致机器损坏的陷阱，仅在 Windows 上失败的构建，默默无效的标志。这个动词可以告诉您任务是否已经解决——或者已知是一个陷阱。

bashy kb context --for "<task>" --rings repo,host --forms note,page --budget 700 --json
bashy kb search "<the task, in your own words>"   # 从一个 ring 中检索
bashy kb show <slug>                              # 完整读取一条记录
bashy kb observe --ring agent --episode E --kind tool-result --ref REF
bashy kb validate <slug> --ring RING --from-gate EVENT_ID
bashy kb note add --candidate --ring agent --episode E --title "…" --body "…"
bashy kb retro                                    # 在完成后进行协调

这是五个管理阶段：context 组装，search/show 检索，observe 记录事件日志，validate --from-gate 验证，note add --candidate 持久化。写入操作通过 --ring repo|host|agent 选择恰好一个存储区；上下文使用 --rings 读取一个命名集合，并使用 --forms note,page,relation,code 过滤记录形状（kb search 使用单数 --form）。kb backlinks 解析入站链接，kb doctor 仅标记问题而不修复它们，并且 kb transfer --from memex 是受支持的传统导入路径。

智能体不得手动编辑 kb 存储区的 pages/*.md 或 graph.jsonl。请使用 bashy kb 动词：它们强制执行归属、候选状态、重复检查、编辑、主所有权、关系 ID 和仅追加历史。

失误是诚实且廉价的：搜索会报告语料库中不包含您的哪些词语以及包含哪些，因此您可以区分*“没有人知道这个”和“我用错了词语提问”*，然后重新表述而不是猜测。如果不存在相关内容并且任务教会了您一些持久化的东西，请贡献出来——bashy kb add --type gotcha --title "…" --description "what + WHEN this applies"——提炼策略，而不是完整记录，将失败表述为防护栏。

inbox——需要注意什么。 发送给您的消息：bashy inbox（默认预览；使用 --from/--search 搜索；使用 bashy mb send 回复）。

一次性阅读所有 MB、固定 Meet 板、Bus 通知和授权角色邮件的视图。MB 仍然是公共发送/历史界面；inbox 避免了逐个传输轮询。

bashy inbox                  # 读取所有入站源
bashy skill show inbox
bashy mb post "<message>"    # 发送给每个人
bashy mb send <agent> "…"    # 发送给一个智能体，或一个选择器

对于必须保持在终端历史之外可发现的状态，请使用明确的主体邮箱。列出和搜索不会消耗；只有 ack 会将一个项目从待处理视图中移除。

bashy inbox list --topic harness --search timeout
bashy inbox human list --topic posix-cert --project dhnt
bashy inbox human send --topic posix-cert --project dhnt --status blocked \
  --ref docs/status.md "Profile D needs review"

智能体和人类邮箱共享相同的过滤器和 JSON 模式。read 保持项目待处理，ack 是显式的，preserve 重新打开它，而 --all 包含已确认的历史记录。保持状态在 1024 个 UTF-8 字节以下，并通过稳定的共享路径、提交、议题、房间或工件引用链接详细信息。

永远不要静默地消费板消息。在读取返回帖子后，当内容简短时，在用户可见的会话控制台中显示完整消息；否则显示发送者/主题、简洁摘要及其所需的操作。工具输出可能被折叠，因此仅内部确认不是操作员可见的协调。

todo——必须完成什么。 工作列表，自动限定范围，就像 kb 一样：当您在一个仓库中时，作用于该仓库，否则作用于主机。

bashy todo list              # 这里打开的内容，按优先级排序
bashy todo add "<title>"     # 记录工作，使其存续于本会话之外
bashy sprint claim last STORY_ID # 认领选定的 sprint 工作
bashy sprint submit last STORY_ID -m "delivery evidence"

所有 sprint 使用相同的生命周期和验收标准；没有为维护保留 sprint 号。显式选择一个 sprint 或使用 last 获取最近创建的卡片。省略 sprint 选择则使用同一个最近的卡片；它不会创建一个 sprint。对独立的仓库待办事项使用 --no-sprint。个人待办事项默认保持独立。阅读 bashy sprint --help。

使用 bashy sprint add "Title" 创建一个 sprint：它会自动分配并返回下一个可用的号码。不需要号码或 next 选择器。

Sprint 故事由项目经理在验证后使用 sprint accept 关闭；通用的 todo done 无法关闭 sprint 故事。

像智能体一样运行命令，而不是像人类一样

• 在变更前预览：bashy --dry-run SCRIPT（带有 BASHY_AGENTIC=1 的智能体可读清单）。
• 预检脚本：bashy check --agent --script SCRIPT。
• 使用捕获的、结构化的结果信封运行： bashy run --check --capture -- SCRIPT。
• 单命令能力查询（标志、特性——跳过试错）： bashy commands COMMAND --features。
• 失败时，读取 stderr 提示：时空顾问解释环境决定的失败（错误的 cwd、缺少工具、磁盘已满），这样您就不会重试一个注定失败的命令。

在运行您没有编写的内容之前，询问运行它意味着什么。 bashy inspect actions [--json] [--kind command|script|agent|skill] 列出此 bashy 可以运行的每个操作，作为一行 facet——kind name identity contract latitude authority effects_declared executor——跨越四个类别：command 是精确且确定性的（shell 运行输入的内容；效果来自其 atlas 记录），agent 绑定根据定义是判断性/智能体化的（执行器 agentlaunch:<tool>，因此其成本和效果是开放的），skill 受其携带的最强契约约束（声明了效果的 dhnt 面、metadata-checks 或 none；一个判断步骤使整个运行成为智能体化），而 script 是一个尚未填充的类别（报告为 0，从不省略）。bashy define NAME 打印单个名称的相同 facet（runs: 行；--json 下嵌套的 action 对象），并且 bashy inspect context --json 携带计数作为 actions: {command, script, agent, skill}。当能够满足任务时，优先选择精确/确定性的行；只有当任务需要自由度时才使用判断性/智能体化的行。

无需 grep 舞步即可浏览代码

• bashy graph impact SYMBOL——哪些代码与符号耦合。
• bashy ast symbols PATH / bashy ast search PATTERN / bashy ast refs SYMBOL / bashy ast map——treesitter 支持，无需模型。
• 共享的仓库内存（其他智能体的发现累积而成的智能体化维基）：使用 bashy graph recall QUERY 读取；使用 bashy graph note / bashy graph observe 贡献；在进行有风险的更改前使用 bashy graph pitfalls。

技能：经过验证的程序，对此主机门控

• bashy skill list——仅适用于此主机坐标的技能（环境门控）；使用 bashy skill show NAME 读取一个技能。
• bashy skill run NAME——执行一个机器可检查的技能；成功契约被验证，每次运行都会留下一个可重新检查的证明。当且仅当契约成立时退出代码为 0。
• bashy skill run NAME --adapt --repair-agent "<your headless CLI>"——自我修复一个失败的技能；已验证的修复每个主机学习一次，并被所有智能体重用。
• 回馈贡献：创建一个技能文件夹，然后 bashy skill learn DIR（准入要求契约在此处实际成立）和 bashy skill promote NAME（人工审核的捆绑包——从不自动发布）。

默认值：来自源钉的命令和 kb 页面

默认的 Bash# 命令和 kb 页面随 Bashy 的源代码一起发布，而不是其二进制文件。第一次 bashy self install（安装程序运行的内容）会设置它们；手动执行： bashy src fetch bashy && bashy --bashsharp "${BASHY_HOME:-$HOME/.bashy}/src/bashy/examples/defaults/bashy-defaults.bsh" apply （使用 status 检查，升级后使用 merge --upgrade：它会添加新的默认值，并列出您自己的页面中覆盖了已更改的页面，以供您协调）。然后默认的 kb 页面会被 bashy kb search 和 bashy recall 自动读取；您自己同 slug 的页面优先。

通过动词编辑目录，绝不要手动操作

永远不要直接编辑 ~/.config/bashy/（或任何 BASHY_*_DIR）下的文件：嵌入的条目是不可变的，每次写入都是写入本地 ring 的写时复制，而只有动词才能执行此操作。bashy <noun> schema 列出 tool/model/agent 接受的带点路径；bashy <noun> set NAME --set path=value（--unset path）编辑一个，bashy <noun> show NAME --field path 读回它。技能：bashy skill add NAME --description "…" 创建一个，bashy skill set NAME / bashy skill rm NAME 编辑和删除，bashy skill show NAME --yaml 打印其记录（skill add FILE.yaml|- 重新导入它）。

编队和工作区（当任务超出单个会话范围时）

• bashy weave …——用于并行智能体运行的隔离按议题工作区；bashy sprint …——计划/连续性；bashy dag TASKS.md——Markdown 定义的任务 DAG。在编排编队之前，请阅读 conductor 技能（bashy skill show conductor）。

经验法则

1. 首先使用 bashy inspect context --json；相信它胜过您自己的探测。
2. 以 kb search + inbox + todo list 开始；以 kb retro 结束。 如果您从本页面记住三个动词，请记住这些。这里的其他所有内容都帮助您执行任务；只有这些能告诉您任务是否已经解决、是否有人在和您谈论它、以及这里还有什么其他工作待办。它们也是唯一价值会复合增长的内容——您写回的内容将是下一个智能体发现的内容，而不是重新发现的内容，而下一个智能体通常是您自己。
3. 当命令会改变状态时，优先使用 bashy run/--dry-run 信封。
4. 在重新推导一个程序之前，检查 bashy skill list——可能已经存在一个经过验证、存档的技能；在解决了可复用的内容后，考虑使用 skill learn 回馈贡献。
5. 用户空间（ls/grep/sed/…）是在进程中运行的，并且在每个平台上都相同——包括 Windows；不要外部调用平台特定的替代方案。