airmosaic-ai

代理行为边界与通用编写规范

English

中文

适用于本仓库的读取、修改、运行、文档生成和共享交付。具体任务的授权范围必须落实到对象、输入、写入位置和外部操作；本规范不扩大权限。

1. 开始和结束时做什么

1. 先读根目录 AGENTS.md 和涉及模块的 SKILL.md，检查当前分支、未提交修改和真实入口。
2. 将请求落实为有限范围：哪些文件、地区/年份/数据、输出、网络行为和计算资源。
3. 按相关类别的使用说明执行；发现文档与代码不一致时，报告具体差异并修正本任务范围内的调用说明。
4. 只修改实现任务所需的内容。保留原始数据、既有结果和他人修改；覆盖前明确目标及授权。
5. 验证结果后检查 diff 和待交付文件，清除私人信息，报告实际完成和未验证事项。

2. 信息边界

信息	本地使用方式	共享文档、代码、Issue、PR、示例及公开日志
用户名、密码、密钥、token、cookie	密码/token 优先存凭据管理器；浏览器认证状态在独立认证根，只在授权工具内部使用	禁止写入；不可通过编码、截断或哈希替代后发布
用户主目录、盘符目录、专用服务器路径	通过本地环境变量或配置解析	使用逻辑根、数据 ID 和仓库相对路径
邮箱、姓名、机构账户、内部主机/IP	仅在任务确有需要且已授权时使用	使用角色或通用占位符；用户明确要求公开的信息按其范围处理
签名下载链接、内网 URL、认证请求头	留在本地授权调用中	用公开来源入口与参数类别代替
浏览器配置、会话和登录状态	属于各成员自己的本地环境	不复制到仓库、其他成员环境或共享附件
原始数据、模型发行包、业务输出	存在授权工作区或只读数据根	可提交元数据、方法、合成案例、获准摘要及明确授权发布且附许可的公开数据副本

官方公开网址、公共论文标识和仓库公开地址可以作为参考来源。任何疑似凭据均不在对话中复述原值，只指出所在文件、行号和类别。

日志与截图同样可能包含私人信息。共享前检查终端提示符、异常栈、文件名、表格内容、浏览器账户区域和 URL 查询参数；仅替换主目录不能保证整个记录已脱敏。

发现真实凭据已经进入版本历史时，停止继续传播并通知维护者，通过服务提供方撤销或轮换。清理当前文件不代表历史泄漏已经消除。改写历史、删除远端内容或执行轮换，按具体授权另行处理。

数据根、配置根和认证根遵循统一存储约定。读取个人配置仅限任务所需文件；不得为“查找登录信息”遍历配置/认证目录、导出 cookie、打印整个环境或将会话打包分享。认证操作与数据下载分别授权，拥有文件访问能力不等于获准读取凭据。

本人已配置的客户端秘密文件只有在明确授权指定客户端/任务后，才能由该可信客户端内部复用。agent 不打开、解析、打印、复制或哈希其内容，不把文件路径或凭据指纹写入共享记录。文档与合成测试使用临时替身配置，不能为了确认“已更新”而读取真实文件或初始化真实认证客户端；本人报告已准备不等于认证已验证。

3. 授权与副作用

操作	行为要求
读取相关代码、公开说明，运行无外部副作用的检查	在任务范围内继续，不重复索要确认
修改指定文档、脚本，生成新的本地结果	使用任务目录，保留原件与他人改动，记录变更
安装依赖、下载数据、调用付费服务、运行耗时模型	检查已有授权、目标范围和资源限制；缺少关键条件时先补齐
登录或切换账号	使用成员自己的会话；遵循来源的认证流程，不采集密码或复制登录态
删除、覆盖原始数据、修改共享模型、取消作业	必须有针对目标的明确授权；检查实际目标和可恢复性
推送、合并、发布、上传结果或对外发消息	核对本次任务是否已授权该外部动作；先准备可审查、已脱敏的内容

已有明确授权覆盖后续必要步骤时继续完成。不要把权限确认变成每一步都问；也不要把“查看可用工具”解释为“下载全部数据”或“运行全部分析”。

4. 通用文档和脚本写法

通用说明按任务职责、能力状态和操作边界编写，不列举具体模型、框架或技术类别。名称、依赖和调用细节放对应技能与分类说明。

方法整理和常规工程验证只读相关说明、接口定义并使用合成输入；真实原始数据的读取、复制或运行须另有明确任务范围。仅方法条目不附具体数据、参数值、实现代码、项目脚本名或源码指纹；第二步仅在已明确声明且经审查的清单技能内允许有界合成计算，不启用该阶段的 run-tool 适配器。

• 从仓库相对位置定位代码、schema 和模板；不依赖作者的盘符、账号名、工作目录或某个 IDE。
• 本地数据通过明确参数或环境变量传入；私人非秘密配置在 AIRMOSAIC_CONFIG_DIR，浏览器状态在 AIRMOSAIC_AUTH_DIR，密码/token 由受控工具从凭据存储按需使用。变量名稳定且有说明；必需配置缺失时给出清楚的错误，不回退到作者的私人目录。
• 示例说明运行目录、解释器、必要参数、预期输出及副作用，并遵循调用环境的真实语法，不混用续行或转义规则。
• 用参数数组启动命令；不把用户内容拼接为 shell 代码，不以 eval 运行文档或模型输出。
• 工具仅接受任务所需参数。已实现的 run-tool 按 schema 和路径角色检查任务参数，拒绝越界输出、网络路径和链接，使用独立任务目录与环境白名单。优先调用该入口；未支持的工具按分类说明使用。它是可信代码的前置检查，不等于 OS 沙箱或原脚本直接调用已被完整隔离。
• 输入默认只读，结果写入独立任务目录；不能用默默覆盖、默默换年份、默默补零来恢复执行。
• 对外日志采用允许字段清单，只保留操作 ID、状态、数量、单位和可公开错误摘要。保留诊断所需的完整记录时，限制在本地授权位置；本地日志也不能写入密码、token、cookie 或认证请求头。
• 不把整个进程环境、浏览器存储、认证请求或本地配置文件打印出来“用于调试”。输出错误应指向缺少的配置名，不展示敏感值。
• 依赖声明到模块级。核心安装不应隐式拉取模型发行包或执行真实下载、登录和分析任务。

5. 结果陈述边界

• 说明文件存在不代表数据年份、质量或权限已验证。
• 数据目录中的声明不代表本机已下载；本地找到文件不代表校验和、schema 或科学口径已通过。
• 有脚本不代表已经安装为宿主工具；有 JSON 示例不代表存在该名称的 API。
• 进程退出成功不代表结果完整；验证跳过、依赖缺失与通过分别记录。
• 场景差值、统计关联、模型推演与经识别的因果效应使用各自准确的名称。
• 基于合成数据的验证不能描述为真实数据全流程通过。

6. 共享前的检查步骤

1. 查看变更清单和新增文件，确认没有夹带缓存、账户文件、真实数据或模型包。
2. 检查机器专用路径、账号信息、密钥格式、认证头、带签名参数的链接；命中只报告位置和类别。
3. 将机器值替换为通用参数，确认命令仍然表达正确的操作，且占位符不会被误认为实际配置。
4. 校对入口、参数和输出描述；标记尚未实现或未运行的内容。
5. 查看最终 diff 与附件，再执行已获授权的共享动作。

自动扫描只能发现部分模式，不能代替人工审查或保证不存在秘密。发现真实敏感值时，不把该值放入测试快照、错误示例或修复说明。

数据与项目结果

实验结果归属对应项目，项目保留代码、配置、评价和审核记录。是否将选定成果纳入 assets/ 由人类科学审核决定，资产内部组织留待后续确定。项目目录写入支持实现前，当前执行器保留既有外部输出契约；通用演示例外依所选适配器而定。不迁移历史结果，不绕过检查，不根据文件已经存在推定通过审核。个人配置、认证与凭据继续分离，见结果与审核约定。

代理的目标/行动/观察、停止条件及生成依据、执行事件和回顾性摘要，遵循统一执行与过程记录规范。具体适配器必须声明实际采集范围，不以事后摘要替代当时事件。

This site is open source. Improve this page.