diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e458ed5 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.worktrees/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cda602d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,49 @@ +# AGENTS.md + +## 适用范围 + +本文件适用于仓库根目录及其全部子目录。 + +## 必读顺序 + +开始任务前,按顺序阅读: + +1. `AGENTS.md` +2. `memory.md` +3. `profile/README.md` +4. 与当前任务直接相关的 `docs/plans/` 文档 + +## 仓库目标 + +本仓库是 `XiyouMobile3G-iOS` 的 GitHub 组织资料仓库。`profile/README.md` 会渲染为组织首页,所有改动应服务于清晰介绍组织、展示项目和引导参与。 + +## 事实来源 + +- 首页实际内容以 `profile/README.md` 为唯一事实来源。 +- 稳定背景、长期决策和待确认事项记录在 `memory.md`。 +- 不要在 `memory.md` 中复制首页正文。 + +## 工作规则 + +- 修改前先查看 `git status`,保留与当前任务无关的用户改动。 +- 优先进行范围最小、易于审阅的修改。 +- 面向访客的内容默认使用简洁、自然的中文,除非任务另有要求。 +- 仅使用 GitHub Markdown 支持的语法与安全 HTML。 +- 不记录或提交 Token、凭据、成员隐私等敏感信息。 +- 长期有效的目标、结构、设计决策,或 `memory.md` 记录的组织与仓库元数据发生变化时,更新 `memory.md`;普通措辞和格式调整无需记录。 +- 未经明确要求,不修改仓库设置、远程地址、分支策略,不提交或推送变更。 + +## 修改流程 + +1. 阅读必读文件并确认任务边界。 +2. 检查目标文件和现有风格。 +3. 实施最小变更。 +4. 长期决策有变化时同步更新 `memory.md`。 +5. 执行验证并检查最终差异。 + +## 验证清单 + +- 运行 `git diff HEAD --check`,确保没有空白错误。 +- 检查 Markdown 标题层级、HTML 标签闭合和表格结构。 +- 检查新增或修改的链接、图片地址和仓库名称。 +- 运行 `git status --short` 和 `git diff HEAD --stat`,确认变更范围符合任务。 diff --git a/docs/plans/2026-08-08-agent-reading-system-design.md b/docs/plans/2026-08-08-agent-reading-system-design.md new file mode 100644 index 0000000..729d480 --- /dev/null +++ b/docs/plans/2026-08-08-agent-reading-system-design.md @@ -0,0 +1,30 @@ +# Agent 阅读体系设计 + +## 目标 + +为 `XiyouMobile3G-iOS/.github` 建立仅服务当前仓库的轻量 Agent 阅读体系,让 Agent 在编辑组织首页前快速获得稳定、准确的上下文。 + +## 文件与职责 + +- `AGENTS.md`:仓库级自动入口,规定必读顺序、仓库目标、修改边界、工作流程和验证清单。 +- `memory.md`:记录组织身份、仓库现状、长期内容决策和待确认事项,不保存敏感信息,也不复制首页正文。 +- `profile/README.md`:GitHub 组织首页内容的唯一事实来源。 + +## 阅读顺序 + +1. 阅读根目录 `AGENTS.md`,理解工作约束。 +2. 阅读根目录 `memory.md`,获取稳定背景和既有决策。 +3. 阅读 `profile/README.md`,确认当前实际页面内容。 + +## 维护原则 + +- 首页结构、目标受众或长期设计决策发生变化时,同步更新 `memory.md`。 +- 普通措辞、标点和格式微调不进入 `memory.md`。 +- `memory.md` 不保存 Token、凭据、成员隐私或其他敏感数据。 +- 修改组织首页后检查链接、Markdown/HTML 结构和变更范围。 + +## 非目标 + +- 不建设跨仓库通用模板。 +- 不引入脚本、自动化工具或复杂文档层级。 +- 本次不修改 `profile/README.md` 的展示内容。 diff --git a/docs/plans/2026-08-08-agent-reading-system.md b/docs/plans/2026-08-08-agent-reading-system.md new file mode 100644 index 0000000..0a16b1b --- /dev/null +++ b/docs/plans/2026-08-08-agent-reading-system.md @@ -0,0 +1,189 @@ +# Agent Reading System Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** 在仓库根目录建立可自动发现的 `AGENTS.md` 与被其引用的 `memory.md`,让 Agent 在修改组织首页前获得稳定上下文和明确约束。 + +**Architecture:** `AGENTS.md` 是覆盖整个仓库的执行入口,定义阅读顺序、事实来源、编辑边界和验证流程。`memory.md` 只保存稳定背景、长期决策和待确认事项;实际首页内容继续由 `profile/README.md` 唯一承载。 + +**Tech Stack:** Markdown、Git、GitHub Organization Profile README + +--- + +### Task 1: 建立 Agent 自动入口 + +**Files:** +- Create: `AGENTS.md` +- Read: `profile/README.md` +- Read: `docs/plans/2026-08-08-agent-reading-system-design.md` + +**Step 1: 确认入口尚不存在** + +Run: `test ! -e AGENTS.md` + +Expected: 命令退出码为 0。 + +**Step 2: 创建最小入口文件** + +创建 `AGENTS.md`,完整内容如下: + +```markdown +# AGENTS.md + +## 适用范围 + +本文件适用于仓库根目录及其全部子目录。 + +## 必读顺序 + +开始任务前,按顺序阅读: + +1. `AGENTS.md` +2. `memory.md` +3. `profile/README.md` +4. 与当前任务直接相关的 `docs/plans/` 文档 + +## 仓库目标 + +本仓库是 `XiyouMobile3G-iOS` 的 GitHub 组织资料仓库。`profile/README.md` 会渲染为组织首页,所有改动应服务于清晰介绍组织、展示项目和引导参与。 + +## 事实来源 + +- 首页实际内容以 `profile/README.md` 为唯一事实来源。 +- 稳定背景、长期决策和待确认事项记录在 `memory.md`。 +- 不要在 `memory.md` 中复制首页正文。 + +## 工作规则 + +- 修改前先查看 `git status`,保留与当前任务无关的用户改动。 +- 优先进行范围最小、易于审阅的修改。 +- 面向访客的内容默认使用简洁、自然的中文,除非任务另有要求。 +- 仅使用 GitHub Markdown 支持的语法与安全 HTML。 +- 不记录或提交 Token、凭据、成员隐私等敏感信息。 +- 只有长期有效的目标、结构或设计决策变化时才更新 `memory.md`;普通措辞和格式调整无需记录。 +- 未经明确要求,不修改仓库设置、远程地址、分支策略,不提交或推送变更。 + +## 修改流程 + +1. 阅读必读文件并确认任务边界。 +2. 检查目标文件和现有风格。 +3. 实施最小变更。 +4. 长期决策有变化时同步更新 `memory.md`。 +5. 执行验证并检查最终差异。 + +## 验证清单 + +- 运行 `git diff --check`,确保没有空白错误。 +- 检查 Markdown 标题层级、HTML 标签闭合和表格结构。 +- 检查新增或修改的链接、图片地址和仓库名称。 +- 运行 `git status --short` 和 `git diff --stat`,确认变更范围符合任务。 +``` + +**Step 3: 验证入口结构** + +Run: `rg -n '^# AGENTS.md$|^## (适用范围|必读顺序|仓库目标|事实来源|工作规则|修改流程|验证清单)$' AGENTS.md` + +Expected: 输出主标题和七个二级标题。 + +**Step 4: 提交入口文件** + +```bash +git add AGENTS.md +git commit -m "docs: 添加 Agent 仓库指引" +``` + +### Task 2: 建立持久上下文 + +**Files:** +- Create: `memory.md` +- Read: `AGENTS.md` +- Read: `profile/README.md` + +**Step 1: 确认记忆文件尚不存在** + +Run: `test ! -e memory.md` + +Expected: 命令退出码为 0。 + +**Step 2: 创建最小持久记忆** + +创建 `memory.md`,完整内容如下: + +```markdown +# Repository Memory + +## 使用方式 + +本文件为 Agent 提供稳定、精简的仓库上下文。仅记录长期有效的信息;页面正文以 `profile/README.md` 为准。 + +## 组织身份 + +- GitHub 组织:`XiyouMobile3G-iOS` +- 展示名称:`XiyouMobile3G - iOS` +- 方向:iOS 与 Apple 平台开发、学习资料、项目规范、开发工具和知识分享 + +## 仓库职责 + +- 仓库:`XiyouMobile3G-iOS/.github` +- 可见性:公开 +- 默认分支:`main` +- 组织首页入口:`profile/README.md` +- 当前阅读体系仅服务本仓库,不作为跨仓库通用模板 + +## 长期决策 + +- `profile/README.md` 是组织首页内容的唯一事实来源。 +- `AGENTS.md` 是 Agent 的仓库级入口,并强制阅读本文件。 +- `memory.md` 不复制首页正文,只保留背景、决策和待确认事项。 +- 面向访客的主要内容默认使用中文。 +- 保持阅读体系轻量,不引入脚本或复杂文档层级。 + +## 待确认事项 + +- 组织首页的美化方向尚未选定。 +- 组织简介、所在地、官网和公开邮箱等 GitHub 组织元数据目前未完善。 + +## 更新规则 + +- 组织定位、首页结构、目标受众或长期设计原则改变时更新本文件。 +- 普通措辞、链接维护、标点和排版微调不记录。 +- 禁止写入 Token、凭据、成员隐私或其他敏感信息。 +``` + +**Step 3: 验证持久上下文结构** + +Run: `rg -n '^# Repository Memory$|^## (使用方式|组织身份|仓库职责|长期决策|待确认事项|更新规则)$' memory.md` + +Expected: 输出主标题和六个二级标题。 + +**Step 4: 提交记忆文件** + +```bash +git add memory.md +git commit -m "docs: 添加仓库持久记忆" +``` + +### Task 3: 验证阅读链路与仓库状态 + +**Files:** +- Verify: `AGENTS.md` +- Verify: `memory.md` +- Verify: `profile/README.md` + +**Step 1: 验证三个必读文件存在** + +Run: `test -f AGENTS.md && test -f memory.md && test -f profile/README.md` + +Expected: 命令退出码为 0。 + +**Step 2: 验证入口引用阅读链路** + +Run: `rg -n 'memory\.md|profile/README\.md' AGENTS.md` + +Expected: 两个路径都至少出现一次。 + +**Step 3: 检查 Markdown 与变更范围** + +Run: `git diff HEAD~2 --check && git status --short --branch && git log -4 --oneline` + +Expected: 无空白错误,工作区干净,历史中包含两个新文件的提交。 diff --git a/docs/plans/2026-08-08-organization-homepage-refresh-design.md b/docs/plans/2026-08-08-organization-homepage-refresh-design.md new file mode 100644 index 0000000..e0f390c --- /dev/null +++ b/docs/plans/2026-08-08-organization-homepage-refresh-design.md @@ -0,0 +1,62 @@ +# 组织首页极简美化设计 + +## 目标 + +在不增加栏目和图片素材的前提下,美化 `XiyouMobile3G-iOS` 的 GitHub 组织首页。首页优先服务准备加入实验室的 iOS 学习者,同时让招聘方、合作方和学校能够快速理解组织定位与代表性项目。 + +## 设计方向 + +采用 Apple 风格的极简黑白排版:克制、清晰、重视内容层级和留白。设计不依赖横幅、插画、Emoji、动态效果或复杂 HTML,以保证 GitHub 深浅色模式、移动端和长期维护的稳定性。 + +## 信息架构 + +保留现有内容区域和顺序: + +1. 品牌区 +2. 关于我们 +3. 精选项目 +4. 知识沉淀 +5. 关注方向 +6. 一起构建 +7. 页脚标语 + +不新增学习路径、成员展示、成果数据或其他栏目。 + +## 视觉层级 + +- 品牌区居中,使用现有组织头像、组织名称、精简标语和三个页内导航链接。 +- 正文全部左对齐,使用标准 Markdown 二级标题。 +- 品牌区与正文之间使用单条分隔线,不堆叠装饰元素。 +- 精选项目继续使用两列表格,统一项目简介的语气与长度。 +- 关注方向继续使用行内代码样式作为低调标签,不引入远端徽章图片。 +- 页脚保留英文标语,拆成两句以形成简洁节奏。 + +## 内容语气 + +- 面向访客的主要内容使用简洁、自然的中文。 +- 首屏标语聚焦 Apple 平台、工程实践和可交付产品。 +- 关于我们保留两段短文:第一段说明资源范围,第二段说明学习和实践方式。 +- 链接文字使用明确动作,如“浏览项目”“查看知识库”“参与共建”。 +- 不夸大规模、成果或活跃度,不加入无法验证的数据。 + +## 可访问性与兼容性 + +- 组织头像保留准确的替代文本。 +- 不使用依赖固定颜色的文字或背景,避免深色模式对比度问题。 +- 不使用宽幅图片或双列卡片,避免移动端横向滚动。 +- 仅使用 GitHub 支持的 Markdown 与简单 HTML 对齐属性。 +- 链接名称应能独立表达目标,不使用含糊的“点击这里”。 + +## 文件与数据流 + +- 修改 `profile/README.md`,它仍是组织首页内容的唯一事实来源。 +- 更新 `memory.md`,记录已确定的极简视觉方向,并移除“美化方向尚未选定”的待确认项。 +- 不新增图片、脚本、依赖或自动生成文件。 + +## 验证 + +- 检查 Markdown 标题层级、表格、HTML 标签和页内锚点。 +- 检查所有仓库链接、组织链接和图片地址。 +- 使用 `git diff HEAD --check` 检查空白错误。 +- 确认最终差异仅包含 `profile/README.md`、`memory.md` 和设计/计划文档。 +- 确认 README 在窄屏下不依赖固定宽度布局。 diff --git a/docs/plans/2026-08-08-organization-homepage-refresh.md b/docs/plans/2026-08-08-organization-homepage-refresh.md new file mode 100644 index 0000000..4a8b65b --- /dev/null +++ b/docs/plans/2026-08-08-organization-homepage-refresh.md @@ -0,0 +1,193 @@ +# Organization Homepage Refresh Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** 在不增加栏目或图片素材的前提下,将组织首页重排为清晰、克制、面向 iOS 学习者的 Apple 风极简页面。 + +**Architecture:** `profile/README.md` 继续作为首页唯一事实来源,只调整现有内容的层级、措辞和间距。`memory.md` 同步保存已确定的长期视觉决策,并移除已经解决的待确认事项。 + +**Tech Stack:** GitHub Flavored Markdown、GitHub README 安全 HTML、Git + +--- + +### Task 1: 重排组织首页 + +**Files:** +- Modify: `profile/README.md` +- Read: `AGENTS.md` +- Read: `memory.md` +- Read: `docs/plans/2026-08-08-organization-homepage-refresh-design.md` + +**Step 1: 验证新首页尚未实现** + +Run: `! rg -q '探索 Apple 平台。沉淀工程实践。构建可交付的产品。' profile/README.md` + +Expected: 命令退出码为 0,证明新首屏标语尚不存在。 + +**Step 2: 用最小实现替换首页正文** + +将 `profile/README.md` 完整替换为: + +```markdown +
+ +--- + +## 关于我们 + +这里汇集与 iOS 开发相关的学习资料、项目规范和开发工具。 + +我们从代码与原理出发,在持续学习、实践与复盘中积累对 Apple 平台开发的理解。 + +## 精选项目 + +| 项目 | 内容 | +| --- | --- | +| [Weather-Forecast-Requests](https://github.com/XiyouMobile3G-iOS/Weather-Forecast-Requests) | 天气预报功能的需求、实现要求与核验资料。 | +| [Raycast-Apple-Developer-Docs](https://github.com/XiyouMobile3G-iOS/Raycast-Apple-Developer-Docs) | 面向 Apple 开发者文档的 Raycast 检索工具。 | +| [3G-share-request-source](https://github.com/XiyouMobile3G-iOS/3G-share-request-source) | 3G Share 的需求说明与配套资源。 | +| [books](https://github.com/XiyouMobile3G-iOS/books) | iOS 与软件开发相关的技术阅读资源。 | + +## 知识沉淀 + +- [**awesome-ios-interview**](https://github.com/XiyouMobile3G-iOS/awesome-ios-interview):系统整理从基础到进阶的 iOS 面试知识。 +- [**tips**](https://github.com/XiyouMobile3G-iOS/tips):记录 iOS 学习与实践过程中值得沉淀的知识点。 + +## 关注方向 + +`iOS` · `Objective-C` · `Apple Developer Documentation` · `Developer Tools` · `Knowledge Sharing` + +## 一起构建 + +欢迎通过 [Issues](https://github.com/orgs/XiyouMobile3G-iOS/issues) 提出建议、补充资料或分享实践。 + +