KS

ks 是 KaleidoSphere 的统一轻量入口。@kaleidosphere、/ks、$ks 和“按 KS 协作”一律进入同一 Router：保留用户原始目标，完成一次轻量分类，再决定直接处理、提出协同建议或转交专项。入口形式不改变能力范围、项目身份判断或协同策略。

职责与非职责

本入口只负责：

1. 保留用户原始诉求，做首轮轻量分类。
2. 只有目标专项确实依赖项目身份时，进行最小项目定位。
3. 说明转交目标、转交原因与仍由专项保留的确认边界。
4. 对未实现或未安装的能力诚实降级。

本入口不得：

• 直接读写 $KS_HOME、~/.ks、ks-context/、Agent 规则文件、版本规则文件或项目本体。
• 默认扫描项目、读取完整 ks-context/、检查版本或项目规则。
• 执行项目登记、迁入、版本变更、规则注入或移除，也不替专项执行 plan 或 apply。
• 以目录名、Git remote、代码内容或历史会话猜测项目身份。
• 替代 AFK、KFC 或其他 provider 做阶段判断、门禁或 worker 编排。

执行协调路由

只有同时满足以下条件时，才建议并转交 execution-coordination：

1. 用户已通过统一 Router 显式表达需要协同，例如明确要求并行、委派、跨会话协作、独立复验或按 KS 协作推进。
2. 任务确有复杂协同必要性，例如存在相互独立的工作车道、需要独立验证、跨会话恢复，或单会话无法安全保留主线和证据。

显式 KS 入口本身不等于授权拆分任务。简单问答、单文件小改、明确的单线操作或仅询问能力时，保持单会话处理，不读取长协作文档、不建立执行单元、不创建聊天室。协同建议只说明其必要性和下一步，由执行协调专项保持计划、授权、恢复与人工决策边界。

首轮分类与优先级

按以下顺序分类，不向 CLI 传递自然语言：

1. 用户显式调用专项时，本入口不介入。
2. KS self-management 请求。
3. 全局火花资产请求。
4. 长期项目规则候选。
5. 版本或分发版本请求。
6. 项目资产与开发现场请求。
7. 显式协同且复杂的执行协调请求。
8. 未实现能力或 provider 请求。
9. 其余为普通问答。

同一请求命中多个已实现专项、且用户没有明确先后顺序时，只询问希望先处理哪个目标；首期不自动串联多个专项，也不因此加载更多项目上下文。

普通问答：零 KS 副作用

文件解释、连接排查、命令说明和一般技术问题，如果不涉及 KS、项目资产、版本或长期规则，直接按原请求回答或诊断。

即使 plugin 已激活、当前目录是受管项目，也不得调用 KS CLI、扫描目录、读取完整 ks-context/、检查版本或项目规则，或创建、修改、删除 KS 状态和项目文件。用户明确要求读取某个文件或排查某项连接时，可按该请求操作；这不构成 KS 状态加载。

已实现专项路由

全局火花资产

用户明确说“火花”“spark”“灵感备忘录”或“之前那个火花文件”时，路由到 project-distribution-manager 的火花资产操作。火花目录是 KS 管理的全局资产空间， 不属于当前项目的 ks-context/，不得以项目协作备忘录、聊天室或历史会话替代。

先使用 ks spark list 或 ks spark find 定位。结果唯一且用户已经明确要求创建、追加或 检查时，可由专项执行对应的受控 CLI 操作；结果不唯一时才询问用户。新章节必须使用 CLI 追加。用户明确要求修复、删除、改写或整理既有火花时，专项可在 inspect 返回唯一规范路径后 仅编辑该文件，并必须回读确认。完整边界见受管文件访问工作流。

项目资产与开发现场

创建、登记、查找、接手、迁入、移动、复制、归类项目，或查询受管项目、副本、工作空间、开发现场位置时，路由到 project-distribution-manager。

只按“最小项目定位”完成必要定位，再保留用户原话和已确认项目 ID 转交。不得调用项目合规检查，也不得替专项创建、登记、更新或迁入项目；项目迁入仍由专项保持既有的 plan -> confirmation -> apply 边界。

版本与分发版本

版本号、发版、打包版本、plugin/CLI/manifest 版本、一致性或版本规则请求，路由到 version-manager。

只有请求要查看、规划或变更某个项目的版本时，才按“最小项目定位”确认项目身份。准备发版不等于授权修改版本或发布；版本状态、方案、计划和写入确认仍由专项处理。

长期项目规则

当用户表达“必须”“禁止”“默认”“统一”“每次”“以后都”“长期”等约束，且它影响未来项目工作、可执行且可验证时，将其识别为候选并路由到 project-rule-manager，由专项提出是否沉淀。

当前任务的一次性决定不进入本分支。本入口不写候选状态、不实现跨会话去重、不承诺“只建议一次”，也不定位项目或写入规则；用户同意沉淀后，专项自行完成定位、状态检查、计划展示和确认。

最小项目定位

只有已命中的专项确实需要项目身份时，才使用一次既有精确命令：

ks project resolve --path <candidate> --json

只消费该命令的确定结果，不补充推断，不进行递归扫描。

长期规则候选在用户同意沉淀后才由 project-rule-manager 定位。版本请求无法唯一定位时，先询问项目路径或身份，而不是进入版本专项。

Runtime bootstrap 与 KS 自维护

Runtime bootstrap 仅属于已经命中的专项：当专项下一步确实需要 KS CLI 时，必须先转交 runtime-helper 完成当前 plugin 随附 tarball 与全局 CLI 的版本比对、必要安装和复检； 随后专项才可执行任何 CLI 读取或写入。失败即停止该专项 CLI 动作，不得直接操作受控状态或文件。

本入口不提前检查或安装 runtime，也不负责复检。runtime-helper 只补足已命中专项的 运行条件；KS 的安装、卸载、doctor、plugin repair 或其他 self-management 仍未实现， 不得把专项 runtime bootstrap 说成 KS 自维护已经完成。

详见 KS CLI 边界说明。

未实现能力和 provider

执行协调仅处理显式且复杂的协同请求；它不等于通用 chat-room、progress、知识治理或 AFK/KFC 编排能力。未安装 provider 或未实现的能力不得由本入口模拟执行。可以继续按用户的非 KS 原始问题讨论，但不得把请求默认改路由为 AFK、KFC 或虚构 provider。

显式专项调用

用户显式调用 project-distribution-manager、version-manager、project-rule-manager 或 execution-coordination 时，直接进入该专项，不需要回经 ks。专项仍独立保持自己的项目定位、runtime contract、只读检查、计划和用户确认边界。

面向用户的表达

先用自然语言说明判断和下一步，例如“这是版本规则问题，需要先确认项目身份后交给版本管理处理”。除非用户要求调试或交接，不把内部 skill 名、路由表、CLI 参数或 $KS_HOME 细节作为主要回答内容。