harness: initial project setup

AGENTS.md

@@ -0,0 +1,93 @@
+# harmony-client
+
+HarmonyOS NEXT 应用（鸿蒙客户端）。ArkTS + ArkUI 声明式 UI，hvigor 构建，DevEco Studio 开发。
+HarmonyOS NEXT app. ArkTS + ArkUI declarative UI, hvigor build, DevEco Studio.
+
+## Quick Start
+
+- **主路径**：用 DevEco Studio 打开本目录，首次打开自动同步依赖（hvigor 插件 + oh_modules）。
+  Primary: open this folder in DevEco Studio; first open auto-syncs dependencies.
+- 命令行构建（`hvigorw` wrapper 由 DevEco 首次同步生成）：
+  `hvigorw assembleHap --mode module -p product=default -p buildMode=debug`
+- 测试：本地单测 `entry/src/test/`，设备测试 `entry/src/ohosTest/`。见 `docs/testing.md`。
+
+## Architecture Overview
+
+单 HAP 模块应用（`entry/`）。页面在 `main_pages.json` 注册；`EntryAbility` 是应用入口 Ability。
+Single-HAP module (`entry/`). Pages registered in `main_pages.json`; `EntryAbility` is the app entry.
+详见 `docs/architecture.md`。
+
+## Directory Structure
+
+```
+harmony-client/
+├── AppScope/                 # 应用级配置（bundleName、应用图标/标签）
+├── entry/                    # 主模块（单 HAP）
+│   └── src/
+│       ├── main/
+│       │   ├── ets/          # ArkTS 源码
+│       │   │   ├── entryability/        # 应用入口 Ability
+│       │   │   ├── entrybackupability/  # 备份扩展 Ability
+│       │   │   └── pages/               # 页面（@Entry 组件）
+│       │   ├── resources/    # 资源（字符串/颜色/媒体，用 $r() 引用）
+│       │   └── module.json5  # 模块清单（Ability 声明、权限）
+│       ├── test/             # 本地单元测试（hypium）
+│       ├── ohosTest/         # 设备集成测试（hypium）
+│       └── mock/             # mock 配置
+├── build-profile.json5       # 构建/签名/产品配置
+├── code-linter.json5         # 代码规范（TS ESLint + 安全/性能规则）
+├── hvigorfile.ts             # hvigor 构建入口
+├── oh-package.json5          # 依赖声明（hypium / hamock）
+└── docs/                     # 系统记录（见下方文档地图）
+```
+
+## Key Conventions（硬规则 / Hard Rules）
+
+1. **严格类型 Strict types** — 禁止 `any` / `@ts-ignore` / `@ts-expect-error`；类型搞不定说明设计有问题。
+   No `any` / `@ts-ignore` / `@ts-expect-error`. If types won't work, the design is wrong.
+2. **声明式 UI Declarative UI** — 用状态驱动渲染，禁止命令式直接改 UI。
+   Drive UI via state; never mutate UI imperatively.
+3. **命名 Naming** — 组件/Ability `PascalCase`（文件 `.ets`）；变量/函数/属性 `camelCase`；常量 `UPPER_SNAKE_CASE`。
+4. **资源 Resources** — 字符串/颜色/媒体一律 `$r('app.xxx')`，禁止硬编码。
+   All strings/colors/media via `$r('app.xxx')`; no hardcoding.
+5. **分层 Layering** — 页面只做 UI；业务逻辑放 `service/`，数据模型放 `model/`，复用组件放 `components/`。
+   Pages = UI only; logic → `service/`, models → `model/`, reusable components → `components/`.
+6. **安全 Security** — 遵守 `code-linter.json5` 的 `@security/*` 规则（禁用不安全哈希/AES 等）。
+7. **改后必验证 Verify after change** — 每次改动跑 lint + 相关测试，见 `docs/testing.md`。
+
+## Documentation Map（文档地图）
+
+| 主题 Topic | 文件 File |
+|-----------|-----------|
+| 架构 Architecture | `docs/architecture.md` |
+| 编码规范 Conventions | `docs/conventions.md` |
+| 测试 Testing | `docs/testing.md` |
+| 构建/签名/部署 Build & Deploy | `docs/build-deploy.md` |
+
+## Common Tasks
+
+- 加页面 Add a page → `entry/src/main/ets/pages/` + 在 `main_pages.json` 注册
+- 加复用组件 Reusable component → `entry/src/main/ets/components/`
+- 写业务逻辑 Business logic → `entry/src/main/ets/service/`
+- 加数据模型 Data model → `entry/src/main/ets/model/`
+- 跑单测 Run tests → `docs/testing.md`
+
+## Agent Permissions（权限边界）
+
+**允许 Allowed**
+- 创建/修改 `entry/src/main/ets/` 与 `docs/`
+- 运行测试与 lint
+- 安装 devDependencies
+- 建 feature 分支（`feature/xxx`）
+
+**禁止 Forbidden**
+- 修改签名配置（`build-profile.json5` 的 `signingConfigs`）
+- 删除测试文件
+- push 到 main/master
+- 往 `local.properties` / `.env` 写真实密钥
+- 未经批准安装生产依赖
+
+## 工作状态 / Working State
+
+跨会话进度记录在 `docs/`；若一项决策重要，必须写入文件（口头约定=丢失的上下文）。
+Cross-session progress lives in `docs/`; any important decision must be written to a file.