Imported from yuandaimaahao/aosp-harness (
codex/features/dev-sidebar/AGENTS.md). Install upstream withnpx skills add yuandaimaahao/aosp-harness --skill dev-sidebar. Copyright stays with the author.
AOSP 树与 dev-sidebar feature 上下文
树级构建约束
envsetup.sh必须在 bash 中source,不要依赖调用者的默认 shell;source后不要直接接管道,避免函数落入子 shell。- 长时间构建必须在后台执行并把输出写入日志;轮询日志,只有出现
build completed successfully成功标记才算构建完成。 - 不得手工编辑
out/下的生成物,所有产物都必须由构建系统生成。 - 修改 public/System API 后必须运行
m update-api,否则 checkapi 会阻断构建。 - 新增系统服务必须同时补齐
system/sepolicy中的 service context、类型和 allow 规则。 - push
framework.jar或services.jar后要评估 ART 缓存风险;校验不一致时,旧 dexpreopt/boot image 或/data/dalvik-cache/可能导致启动缓慢或失败。
源码导航
- 使用
rg配合源码阅读定位模块、符号和调用链。 - 先按仓库和路径缩小范围,再搜索 JNI 注册名、全限定
Class::method等高信息量锚点,避免用onTransact一类泛词扫全树。 - 这里没有建立完整索引,也不得把搜索结果描述成索引结论;影响面判断必须给出源码路径、关键符号和仍未确认的边界。
子代理任务卡
派发子代理时只提供完成局部任务所需的任务卡,不广播整份 feature 上下文。任务卡必须包含:
- 目标:要交付或回答的具体问题;
- 路径:允许读取或修改的仓库和目录;
- 事实:会改变结论的版本、ABI、JNI 或生成代码信息;
- 约束:禁止目录、只读要求、构建和部署限制;
- 证据:期望返回的源码位置、命令结果、验证结论和未确认项。
feature: dev-sidebar
目标是在 AOSP 17 中新增系统服务、native 合成侧和常驻边栏应用。
允许修改的仓库只有:frameworks/base、frameworks/native、packages/apps/SidebarApp、build/make、system/sepolicy。机器可读清单位于 features/dev-sidebar/repos.tsv;开始工作前用 ./features/dev-sidebar/check-branch.sh 检查所有涉及仓是否位于 dev-sidebar 分支。
必须遵循的流程路由
- 修改
frameworks/base/services/**前必须显式读取并按当前任务使用$build-services-jar。 - 修改
system/sepolicy/**前必须显式读取并按当前任务使用$build-sepolicy。 - 整个 feature 交付前运行
./features/dev-sidebar/verify-sidebar.sh;完成条件按下方两层验收判定。
frameworks/base
新增 SidebarService 和 ISidebar.aidl,并在 SystemServer 注册 sidebar 服务。AIDL 进入 public/System API 时必须运行 m update-api;服务实现和 SystemServer 变更遵循 $build-services-jar。
frameworks/native
新增 SidebarFlinger native 合成实现并接入合成服务启动链。使用唯一类名、全限定 C++ 方法和注册点导航;若触及缩放态触摸坐标映射,先明确 input 链路影响面。
packages/apps/SidebarApp
常驻边栏应用通过 ISidebar 与系统服务通信。修改前确认平台签名、privapp 权限、产品安装位置及应用进程存活策略。
build/make
仅接入 dev-sidebar 所需模块和产品配置。不要直接修改 out/ 里的产品文件来模拟构建结果。
system/sepolicy
为 sidebar 服务补齐 service_contexts、service type、域访问与必要 allow 规则。策略修改遵循 $build-sepolicy,验证时检查新的 AVC denial。
与 intent 协作及完成条件
-
从源码树根工作,分别识别各 Git project 根和规划目录;不要用树根的一次
git status代表所有涉及仓。repos.tsv与现有检查器是源码仓范围及分支的事实来源,小需求只记录本次涉及的子集和理由。 -
intent 文档位置依次采用:用户明确指定 → 已有文档位置 → 本 feature 的
features/dev-sidebar/.intent/→ intent 默认位置。新路线图为features/dev-sidebar/.intent/roadmap.md,展开需求使用固定编号的001-需求名称.md等 Markdown,实际审查按轮次写入features/dev-sidebar/.intent/review/001-需求名称-1.md等文件;已有资料原位续用,不搬迁或预建空文件。 -
每份小需求记录当前 feature、目标与验收、涉及仓子集和路径及理由、构建与验证入口、环境依赖、实际证据和剩余事项;不另建状态文件。主 agent 可更新当前 feature 的上述规划和审查资料,包括明确指定或已有的规划位置;这不扩大业务源码可修改范围。上下文只维护目标摘要、执行约束与文档入口,详细任务和进展维护在原文档中。
-
每次修改相关源码前读取对应流程 skill,并运行
./features/dev-sidebar/check-branch.sh;同轮后续写操作未被 hook 覆盖时重新检查。若需求文档的 feature 与已加载上下文不同,停止依赖旧上下文的写入,按下述启动入口重新准备并新建会话,不自行切换分支或热换上下文。 -
worker 任务卡包含源码根、feature、允许修改的仓及路径、相关约束、验收命令和共享资源。由主 agent 维护共享需求文档;同一
out/的构建、同一设备或 CVD 组的操作串行执行。审查逐仓确定基线,包含相关已提交、未提交及未跟踪实现;基线不可靠时检查明确模块并披露限制。 -
小需求按事先明确的自身验收和必要回归判断交付;独立审查仅在用户要求或项目规则要求时成为完成条件。缺少已要求的审查、构建环境或必要设备证据时如实报告部分完成。
-
整个 feature 交付须全部需求完成,并运行
./features/dev-sidebar/verify-sidebar.sh,最终精确输出RESULT PASS且退出 0。其他小需求尚未实现不能阻止已满足自身验收的前项交付,但必须保留 feature 未完成状态。不能事后把失败检查改为“不适用”;相关失败须调查。 -
规划完成、离线 Harness 可用、编译通过、小需求交付和 feature 真机验收分别报告。
RESULT INCOMPLETE即使在--demo --allow-skip下退出 0,也不是验收通过。 -
需求澄清、设计和任务规划不触发构建;读取流程只提供当前任务的方法,构建、部署及验收按已授权范围分别执行。调用
intent-implement不扩大设备操作授权,也不自动启动另一 intent 阶段或安装 skills。 -
恢复入口:
.codex/bin/codex-feature;GUI 用.codex/bin/prepare-feature后从源码树根新建任务。 -
intent 已独立安装且用户明确选择后,可显式调用
$intent-roadmap 为 dev-sidebar 规划路线图;单项规划用$intent-plan features/dev-sidebar/.intent/001-需求名称.md,实现用$intent-implement features/dev-sidebar/.intent/001-需求名称.md,需要审查时用$intent-review features/dev-sidebar/.intent/001-需求名称.md。当前没有实际规划文档时,不把这些示例路径报告为已创建。
