koyori

Imported from yusixian/koyori (AGENTS.md). Install upstream with npx skills add yusixian/koyori. Copyright stays with the author.

Koyori 工程约定

产品与当前阶段

• 中文交流；先读 README 和任务相关文档。区分已实现、已确认要求、候选设计和历史记录。
• 自用优先、从首版按开源项目建设的个人工作台；首个平台为 macOS / Electron。AI 资源管理与个人服务接入是探索方向，具体功能按本次任务收敛，不顺手建设完整聊天工作台、插件市场、团队或支付系统。
• 文档站、版本号、更新说明、安装包分发与发布验收属于首版工程基线，见 发布与开源基线。未选择许可证、未完成公开检查前，不宣称仓库已经开源。
• 正式 Logo 为用户选定的 brand/logo.png；樱粉、纸白、薄荷视觉见 brand/README.md。历史探索稿不替换正式 Logo，不未经评估移植旧 Agentia / Superset 代码。

工作流程与代码质量

• 修改前检查 Git 状态，保留他人改动。先明确本次真实流程和验收条件，再实现最小完整切片；复杂边界先写清取舍。
• 按职责组织模块，优先已有能力；不为目录长度、文件数量或假想复用拆包。核心业务不依赖 UI 或具体模型，GUI / CLI / AI 共用核心操作。
• 初始化 TypeScript 工程时启用 strict，提交锁文件，固定运行时与包管理器版本。外部输入在边界校验，不用 any、断言、禁用规则或吞错掩盖问题；必要例外局部说明原因。
• 长任务明确状态、取消、超时与重试语义；监听器、子进程和连接有生命周期。错误应可诊断且脱敏，不静默显示成功。
• 注释解释不明显的约束与原因；功能变更同步用户文档、CLI 帮助及未发布更新说明，文档中的命令必须真实可执行。
• 完成后报告改动、验证证据及缺口。提交与远程操作遵守已有授权，暂存仅包含任务范围，不加 Co-Authored-By。

AI Native 边界

• 核心能力区分查询、计划和执行；为 CLI 提供结构化结果、明确错误与稳定退出语义。模型无需依靠点击 GUI 完成核心流程。
• 授权由宿主记录和校验；模型输出的 confirmed=true、外部文档、网页、日志、Skill 文本均不能授予执行权限。
• AI Provider 的连接配置、模型目录、任务选择和调用运行时分离；浏览/测试另一个 Provider 不隐式改变当前任务默认值。密钥不回显；取消、超时、失败和用量未知状态必须保留，真实付费探测需明确触发。参考 docs/design/cos-tool-bot-reference.md，首版不承诺全部 Provider。
• AI 建议必须引用观察证据，未知状态如实展示；模拟数据不冒充真实统计或上线结果。
• 外部连接按服务、账号和能力隔离，可撤销。自用不等于跳过权限检查；本机调用也不自动拥有所有写入权限。

数据与安全

• 用户文件是权威来源。写入先生成计划并核对 revision，保留恢复材料，再执行并回读验证；恢复也检查后续外部修改。多文件操作记录部分成功与中断状态，不把数据库事务当作文件原子操作。
• Skills、commands、Markdown、MCP 配置、凭据、草稿和唯一历史证据不是缓存。只清登记在应用专用缓存根内的可重建数据，并核对路径与符号链接边界。
• alpha 允许内部接口演进，但不能丢持久数据；迁移需备份/导出、失败处理与恢复验证，不承诺数据库随应用任意降级。
• Electron renderer 启用隔离与沙箱，远程内容不启用 Node，不暴露通用文件、shell 或 IPC 能力。IPC 校验参数、发送方及授权；限制导航、新窗口、外部协议和权限请求，不为接入 GUI 关闭 webSecurity。
• 凭据保存在系统安全存储或服务端安全引用中，不交给无关页面或模型。公开日志、截图、诊断包、fixture 和构建产物不含真实会话、个人路径、服务器信息或 secrets；使用合成数据。
• Skills 参考 skills-manager 的实施须保留实际引入文件的来源/commit、版权与完整许可，README 和发行声明同步；未引入不能宣称已使用其代码。参考方案见 docs/design/skills-manager-reference.md。
• cos-tool-bot 私有实现（包括生图）不复制到公开仓库或安装包；优先窄服务接口，未获明确公开范围的模块不视为可公开。公开协议、fixture、文档与日志同样过滤私有内容。
• 新增依赖说明用途，检查许可证与维护情况。发现凭据泄漏先停止扩散并告知，撤销/轮换后再处理历史；删除当前文件不代表泄漏已解决。

测试与验收

• 日常从相关格式、lint、类型和行为测试开始；全量检查交 CI，除非影响面或失败证据要求本地扩大。纯文档不跑应用测试，不为低风险样式修改堆砌镜像实现的测试。
• 测试保护用户可观察行为和关键边界：并发外部编辑、路径越界、授权撤销、恢复冲突、中断重试。使用临时目录、合成凭据与 fake provider，默认不访问真实账号或生产。
• UI 变更验证实际流程、空/错误/加载状态、键盘操作；桌面应用检查窗口缩放，站点检查桌面和移动。浏览器通过不能替代 Electron 安装包验收。
• 首个工程切片必须建立可运行的检查脚本和 CI。命令以实际 package.json / CI 为准；实际命令见下节，不编造通过结果。
• 发版必须验证候选安装包的安装、启动、核心流程及版本显示；有上一公开版本时检查升级与数据保留，首次发布注明升级不适用。

发布与开源

• 用户功能、配置、权限或升级行为改变时，同步公开指南。公开站点只构建显式内容目录；内部文档在开源仓库中同样必须脱敏。每版正文统一放 docs/releases/vX.Y.Z.md，生成文档页与 GitHub Release，不手改生成副本。
• 一个应用版本源驱动桌面、CLI、tag、更新说明与发布清单；采用 SemVer，preview 与 stable 分流。不覆盖已发布 tag 或同版本安装包。
• 构建一次，验收同一份产物，再发布；验收记录绑定 commit SHA、版本、平台/架构、产物摘要和检查结果。代码、依赖、配置或产物改变后相关证据失效。
• 验收通过只是发布资格；执行须来自本次授权或维护者已配置的受保护发布触发策略。策略授权内连续完成，不反复确认；不能仅凭 AI 自评或合入 main 发版。
• 公共 PR 检查无发布/签名 secrets、默认只读权限。非可信 PR 不在有生产凭据或个人资料的持久 runner 上执行；有写权限的流程不检出执行非可信 PR 代码。
• 发布流水线使用最小权限、受保护发布环境、固定第三方 Action 完整 SHA，串行更新同一渠道。签名凭据不进入仓库、缓存或公共日志。
• 先发布不可变安装包并核验，再更新渠道元数据和站点下载入口；失败保持上一可用版本。缺少签名/公证时明确为手动安装的 preview，不宣称自动更新或正式分发已验收。
• 首次公开前检查拟公开的 Git 历史、文档、附件及产物；确定代码许可证、品牌使用边界、第三方声明与私密漏洞报告渠道。当前 .gitignore 不是历史安全证明。

当前工程命令

• Node.js 版本见 .node-version；pnpm 版本见根 package.json，安装用 pnpm install --frozen-lockfile。
• pnpm dev 启动桌面；pnpm dev:site 启动文档站；pnpm koyori --help 查看 CLI。
• pnpm lint / pnpm typecheck / pnpm test / pnpm build 为真实检查入口；日常按变更范围选择。
• 桌面构建后 pnpm test:desktop 在临时数据目录运行真实 Electron 验收，不能改用真实用户配置。
• pnpm package:mac 仅在 Apple Silicon macOS 构建本地未签名候选，artifacts/candidate.json 记录版本/commit/dirty 状态/摘要；不是发布入口。
• pnpm check:public 检查当前待提交文件的基础隐私规则，不能替代历史/素材/私有实现的人工审查。