# connecting-docs

**Repository Path**: connecting_repo/connecting-docs

## Basic Information

- **Project Name**: connecting-docs
- **Description**: Connecting 产品线（connecting_repo）组织级文档枢纽：仓库地图、工具链工作流、术语表、快速开始、FAQ、贡献指南。统一入口，不含代码。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/connecting_repo/connecting-docs/blob/master/QUICK_START.md
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: docs, docments, guide, workflow

## README

# Connecting 产品线文档枢纽

> **组织**：`connecting_repo`（Gitee）
> **角色**：本仓库是 Connecting 产品线的**组织级文档枢纽**，不包含任何代码。
> **目的**：为开发者与 AI 编程助手提供统一入口——先看[组织全貌](#一组织全貌仓库地图)，再按[工具链工作流](#二工具链工作流主线)行动，细节文档分散在各交付仓库由本枢纽索引。
> **新手入口**：想直接跑通一遍？先读 [`QUICK_START.md`](./QUICK_START.md)；常见问题见 [`faq.md`](./faq.md)。

---

## 一、组织全貌（仓库地图）

Connecting 产品线由多个 Git 仓库组成，按"集合层 → 应用层 → 基础层 → 工具层"组织：

| 仓库（Gitee 路径） | 层级 | 职责 | 文档位置 |
|-------------------|------|------|---------|
| **`connecting-docs`**（本仓库） | 组织枢纽 | 全貌 + 工作流主线 + 术语表 | 此仓库根目录 |
| **`connecting_demos`** | 集合层 | 所有板卡示例的总入口（只存子模块指针） | `connecting_demos/README.md`（板卡索引） |
| **`demo-<芯片>-<板卡>-<业务类型>`** | 应用层 | 单板卡示例工程（如 `demo-stm32f407-alientek-discovery-baremetal`） | 各 demo 仓库 `README.md` + `tool/` |
| **`connecting_middleware`** | 基础层 | 中间件核心：预编译库 + 头文件 + 配置（LGPL） | `connecting_middleware/docs/public/`（对外）+ `docs/internal/`（内部） |
| **`info-extractor`** | 工具层 | 元数据提取工具（从 elf/map/源码提取） | `info-extractor/docs/public/`（用户）+ `docs/internal/`（开发） |
| **`connecting-host-tool`** | 工具层 | 上位机联调软件（文档已就绪） | `connecting-host-tool/docs/public/用户操作指南.md` |

> **命名规范**：板卡仓库名格式 `demo-<芯片>-<板卡>-<业务类型>`，业务类型段为 `baremetal` / `rtos` / `app-<名称>`。
> 仓库结构与命名详情见 [`repository-architecture.md`](./repository-architecture.md)（本文档已从中间件仓库迁出至组织枢纽）。

### 关系图

```
connecting_repo/（组织）
│
├── connecting-docs/          ← 你在这里（组织枢纽）
│
├── connecting_demos/         ← 集合层（子模块指针）
│   ├── demo-stm32f407-alientek-discovery-baremetal/  → 子模块引用 connecting_middleware
│   └── demo-<其他板卡>/...
│
├── connecting_middleware/    ← 基础层（库 + 头 + 配置）
│
├── info-extractor/           ← 工具层（提取工具）
└── connecting-host-tool/     ← 工具层（上位机，文档已就绪）
```

---

## 二、工具链工作流主线

完整的"从零到可用"任务流见 **[`workflow.md`](./workflow.md)**。摘要：

| 步骤 | 任务 | 主文档 |
|------|------|--------|
| ① | 获取代码（clone 含子模块） | `connecting_demos` README + `middleware` README |
| ② | 下载预编译库 | `board_porting_guide.md` §1（`setup_libs.bat`） |
| ③ | 编译条件适配 | `board_porting_guide.md` §2（编译器/ABI/功能开关） |
| ④ | 移植 / 集成应用 | `application_developer_guide.md` + `API_Reference.md` + `driver_spec.md` |
| ⑤ | 提取工具生成元数据 | `board_porting_guide.md` §4 + `info_extractor/docs/public/config_guide.md` |
| ⑥ | 上位机联调 | `connecting-host-tool/docs/public/用户操作指南.md` |

> **AI 提示**：执行具体任务时，先读 [`workflow.md`](./workflow.md) 定位步骤，再打开对应细节文档。所有链接均指向各仓库 `docs/public` 或板卡 `README`，无需猜测路径。

---

## 三、文档分层约定

为降低维护成本与 AI 误读，所有仓库统一采用两层：

- **`public/` / 对外文档**：随交付物发布，供使用者与 AI 阅读（API、配置、集成、移植指南）。
- **`internal/` / 内部文档**：架构、需求、详细设计、发布流程，**不随交付物发布**。

中间件对外文档索引（`connecting_middleware/docs/public/`）：

| 文档 | 内容 |
|------|------|
| `application_developer_guide.md` | 应用开发者视角：如何调用中间件 |
| `API_Reference.md` | 对外 API 参考 |
| `Config_Reference.md` | `middleware_config.h` 配置项详解 |
| `driver_spec.md` | 驱动适配层接口规范 |
| `demo_integration.md` | demo 与中间件集成说明 |
| `board_porting_guide.md` | **板卡适配 AI 指南**（获取→下库→编译适配→移植→提取）—— *位于各板卡 demo 仓库 `docs/`，非中间件仓* |
| `repository-architecture.md` | 仓库结构与命名规范（三层分离 + 子模块依赖） |
| `AI_Skill_Guide.md` | 中间件 AI Skill 引导（含 references 详细 API/移植指南） |
| `comment_style.md` | 代码注释规范（**工具链统一要求**，所有仓库自有代码必须遵守） |

---

## 四、术语表

见 **[`glossary.md`](./glossary.md)**。摘要：

- **free / pro**：中间件编译开关 `MIDDLEWARE_PRO_VERSION` 的两种形态，当前发布为 free 版。
- **子模块（submodule）**：demo 通过 Git 子模块引用 `connecting_middleware`，不复制源码。
- **预编译库**：中间件以 `.lib`/`.a` 形式从 Gitee Release 分发，不进 git。
- **提取工具**：`info_extractor`，从编译产物生成上位机可用的元数据（JSON/DCM）。
- **业务类型段**：板卡仓库名末尾的 `baremetal`/`rtos`/`app-<名称>`。

---

## 五、本枢纽文档索引

| 文档 | 用途 |
|------|------|
| [`QUICK_START.md`](./QUICK_START.md) | 完整工作流主线：从克隆到上位机联调，一步一命令 |
| [`faq.md`](./faq.md) | 常见问题（概念 / 安装 / 联调 / 合作） |
| [`workflow.md`](./workflow.md) | 工具链工作流详细步骤与文档定位 |
| [`glossary.md`](./glossary.md) | 术语表（free/pro、子模块、预编译库等） |
| [`repository-architecture.md`](./repository-architecture.md) | 仓库结构与命名规范 |
| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | 贡献指南：报告 Bug、提功能、MR 流程与许可证边界 |

---

## 六、如何贡献文档

参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。要点：


1. 细节文档写在**所属交付仓库**的 `docs/public` 或 `docs/internal`，不要在本枢纽复制内容。
2. 本枢纽只维护**全貌、工作流主线、术语表**，并用链接索引各仓库文档。
3. 新增仓库/板卡时，同步更新本 README 的[仓库地图](#一组织全貌仓库地图)与 [`workflow.md`](./workflow.md)。